@designcrowd/library.brand-page 6.2.11 → 6.2.12

package/lib/src/brand-page-maker/utils/rich-text-editor.util.js

@@ -1,18 +1,370 @@
-import { STYLE_THEME_KEYS, } from '@brand-page';
+import { STYLE_THEME_KEYS, CANONICAL_TEXT_STYLE_TYPES, } from '@brand-page';
 import { collectRteTextColors } from '@shared/color-strategies/rte-color';
-import { ESCAPED_NEWLINE_CHARACTER } from '@src/constants/ui';
-import { getRenderText } from '@brand-page/utils';
+import { composeTextDecoration, localTextDecoration, roleVarRef, } from '@shared/text-role-typography.util';
 import createDomPurify, {} from 'dompurify';
 import Color from 'color';
-import { isHrefPageId } from '../composables/rich-text-editor/hyperlink';
-import { RTE_SECTION_FIELD_PAIRS, } from '@shared/color-strategies/rte-field-pairs';
+import { isHrefPageId } from '@shared/rte-link.util';
+import { RTE_SECTION_FIELD_PAIRS, PLAIN_TEXT_PAIR_SECTIONS, } from '@shared/color-strategies/rte-field-pairs';
 // Re-exported below so every existing caller keeps importing them from here; they
 // live in a leaf module because this one pulls dompurify at runtime.
-import { isTiptapDocument, isRteHtmlString } from './rte-shape';
-export { isTiptapDocument, isRteHtmlString };
-// 'text' has special textItems handling, so it's not in the map but is RTE-enabled
+import { getRteJsonPlainText, isRteHtmlString, isTiptapDocument, } from '@shared/rte-shape.util';
+export { getRteJsonPlainText, isRteHtmlString, isTiptapDocument, } from '@shared/rte-shape.util';
+/**
+ * BP-5969 (ADR-0019, Option B): a block linked to a CANONICAL role gets its typography
+ * from the page-scoped CSS class (`text-role-css.util`), so authoring must NOT bake
+ * family/size/spacing/line-height/weight/style/decoration into the marks — a value baked
+ * post-migration would pin the block forever (migration-22 never re-runs to strip it).
+ * Colour is exempt (it isn't in the class). Legacy/unlinked types have no class, so they
+ * still bake inline. Mirrors `TextWrapper`'s canonical-only `roleClass`.
+ */
+export const isCanonicalLinked = (style) => !!style?.textStyleType &&
+    CANONICAL_TEXT_STYLE_TYPES.includes(style.textStyleType);
+/** True when a mark value is a role reference (`var(--role-…)`) rather than a literal. */
+export const isRoleVarRef = (value) => typeof value === 'string' && value.startsWith('var(--role-');
+// A prop's CSS "default" keyword that renders identically to the prop being absent — e.g.
+// font-weight:normal == no font-weight. The toolbar writes these literals when a format is
+// toggled OFF (bold→'normal', italic→'normal', underline/strike→'none'); a role that simply
+// omits the prop must still read as equal, so both collapse to '' for the role-equality compare.
+const DEFAULT_EQUIVALENT_VALUE = {
+    fontWeight: 'normal',
+    fontStyle: 'normal',
+    textDecoration: 'none',
+    lineHeight: 'normal',
+    letterSpacing: 'normal',
+};
+/**
+ * Normalise a typography value for a role-equality compare: quote-strip + trim for fontFamily,
+ * trim otherwise, then fold a prop's default keyword (`normal`/`none`) to '' so it matches a role
+ * that leaves the prop unset (`'normal'`/`'none'`/absent are the same override-wise).
+ */
+export const normTypographyValue = (key, value) => {
+    const trimmed = key === 'fontFamily'
+        ? (value ?? '').replace(/['"]/g, '').trim()
+        : (value ?? '').trim();
+    return trimmed === DEFAULT_EQUIVALENT_VALUE[key] ? '' : trimmed;
+};
+/**
+ * BP-5969 — the RTE mark value to write for a typography attr change: the role var (so the run
+ * stays linked and follows role edits) when the picked value equals the linked role, else the
+ * literal raw override. `roleStyle` undefined (legacy/unlinked block, no role class to resolve a
+ * var) → always the literal. The equality test runs at the mutation point, per ADR-0019.
+ */
+export const roleVarOrLiteral = (markAttr, picked, roleStyle) => {
+    const ref = roleVarRef(markAttr);
+    const roleValue = roleStyle?.[markAttr];
+    return ref &&
+        typeof roleValue === 'string' &&
+        normTypographyValue(markAttr, picked) ===
+            normTypographyValue(markAttr, roleValue)
+        ? ref
+        : picked;
+};
+const BLOCK_TYPOGRAPHY_ATTRS = [
+    'fontFamily',
+    'fontSize',
+    'lineHeight',
+    'letterSpacing',
+    'fontWeight',
+    'fontStyle',
+    'textDecoration',
+];
+const LINK_TYPOGRAPHY_ATTRS = BLOCK_TYPOGRAPHY_ATTRS.filter((attr) => attr !== 'textDecoration');
+// A link's underline is the link's own look (the toolbar and AutoLink add it), not a
+// typography choice, so it neither lights the asterisk nor joins the block's value.
+const typographyAttrsOf = (node) => node.marks.some((mark) => mark.type.name === 'link')
+    ? LINK_TYPOGRAPHY_ATTRS
+    : BLOCK_TYPOGRAPHY_ATTRS;
+export const LEGACY_TYPOGRAPHY_MARKS = {
+    fontWeight: ['bold'],
+    fontStyle: ['italic'],
+    textDecoration: ['underline', 'strike'],
+};
+/**
+ * A run's marks without the legacy semantic marks (`<strong>`/`<em>`/`<u>`/`<s>`) that compete with
+ * `attrs`. A link keeps its underline, as Reset does (`restoreLinkUnderlines`).
+ */
+export const withoutTypographyMarks = (marks, attrs, isLink) => {
+    const dropped = new Set(attrs.flatMap((attr) => LEGACY_TYPOGRAPHY_MARKS[attr] ?? []));
+    return marks.filter((mark) => !dropped.has(mark.type) || (isLink && mark.type === 'underline'));
+};
+/**
+ * One text run's typography: its `textStyle` attrs, falling back to a legacy semantic mark
+ * (`<strong>`/`<em>`/`<u>`/`<s>`) for un-migrated / pasted runs (mirrors `formatting.ts` `effective`).
+ * An absent attr is undefined — the run inherits the role class.
+ */
+export const runTypography = (node) => {
+    const textStyle = node.marks.find((mark) => mark.type.name === 'textStyle');
+    const attrOf = (attr) => {
+        const value = textStyle?.attrs?.[attr];
+        return typeof value === 'string' && value !== '' ? value : undefined;
+    };
+    const has = (markName) => node.marks.some((mark) => mark.type.name === markName);
+    const legacyDecoration = [has('underline') && 'underline', has('strike') && 'line-through']
+        .filter(Boolean)
+        .join(' ') || undefined;
+    return {
+        fontFamily: attrOf('fontFamily'),
+        fontSize: attrOf('fontSize'),
+        lineHeight: attrOf('lineHeight'),
+        letterSpacing: attrOf('letterSpacing'),
+        fontWeight: attrOf('fontWeight') ?? (has('bold') ? 'bold' : undefined),
+        fontStyle: attrOf('fontStyle') ?? (has('italic') ? 'italic' : undefined),
+        textDecoration: localTextDecoration(attrOf('textDecoration') ?? legacyDecoration, textStyle?.attrs?.textDecorationReset === true),
+    };
+};
+const isRoleEqualLiteral = (attr, value, role, previousRole) => value !== undefined &&
+    !isRoleVarRef(value) &&
+    normTypographyValue(attr, attr === 'textDecoration'
+        ? composeTextDecoration(previousRole?.textDecoration, value)
+        : value) === normTypographyValue(attr, role[attr]);
+/**
+ * True when any run's typography differs from `role` — the role dropdown's asterisk. Unlike
+ * `readBlockTypography`, one bold word counts. Absent attrs and role refs follow the role.
+ */
+export const hasRunTypographyOverride = (editor, role) => {
+    let found = false;
+    editor.state.doc.descendants((node) => {
+        if (found)
+            return false;
+        if (!node.isText || !node.text)
+            return;
+        const run = runTypography(node);
+        found = typographyAttrsOf(node).some((attr) => run[attr] !== undefined &&
+            !isRoleVarRef(run[attr]) &&
+            !isRoleEqualLiteral(attr, run[attr], role));
+    });
+    return found;
+};
+/**
+ * "Apply changes to all", on the live editor: every run value now equal to `role` becomes its
+ * `var(--role-*)` ref (or is unset when the role leaves the attr undefined), and the legacy mark it
+ * came from is dropped. A value that still differs — a word-level override — stays. Colour and the
+ * selection are untouched. The editor twin of `relinkRoleEqualMarks`; the caller runs the chain.
+ */
+export const relinkRoleEqualRunsChain = (editor, role, previousRole) => editor.chain().command(({ tr }) => {
+    const { schema } = tr.doc.type;
+    const textStyleType = schema.marks.textStyle;
+    // Mark steps never shift positions, so walking the pre-edit doc stays valid.
+    tr.doc.descendants((node, pos) => {
+        if (!node.isText || !node.text)
+            return;
+        const run = runTypography(node);
+        const relinked = typographyAttrsOf(node).filter((attr) => isRoleEqualLiteral(attr, run[attr], role, previousRole));
+        if (!relinked.length)
+            return;
+        const from = pos;
+        const to = pos + node.nodeSize;
+        const attrs = {
+            ...node.marks.find((mark) => mark.type === textStyleType)?.attrs,
+        };
+        relinked.forEach((attr) => {
+            attrs[attr] = role[attr] ? roleVarRef(attr) : null;
+            if (attr === 'textDecoration')
+                attrs.textDecorationReset = null;
+            LEGACY_TYPOGRAPHY_MARKS[attr]?.forEach((name) => {
+                if (schema.marks[name])
+                    tr.removeMark(from, to, schema.marks[name]);
+            });
+        });
+        // Attr defaults are '' or null, so any falsy value is empty (as Tiptap's `removeEmptyTextStyle`).
+        if (Object.values(attrs).some(Boolean))
+            tr.addMark(from, to, textStyleType.create(attrs));
+        else
+            tr.removeMark(from, to, textStyleType);
+    });
+    return true;
+});
+/**
+ * The block's whole-box typography — what "Apply changes to all" can promote into the role. A prop
+ * is included only when UNIFORM across every text run: one bold word has no single value to promote
+ * (`hasRunTypographyOverride` still flags it). A role-var ref rides through as the block value; the
+ * caller (`getTypographyOverride`) treats it as "linked", not an override.
+ */
+export const readBlockTypography = (editor) => {
+    const seen = Object.fromEntries(BLOCK_TYPOGRAPHY_ATTRS.map((attr) => [attr, new Set()]));
+    let hasText = false;
+    editor.state.doc.descendants((node) => {
+        if (!node.isText || !node.text)
+            return;
+        hasText = true;
+        const effective = runTypography(node);
+        typographyAttrsOf(node).forEach((attr) => seen[attr].add(effective[attr]));
+    });
+    if (!hasText)
+        return {};
+    const typography = {};
+    BLOCK_TYPOGRAPHY_ATTRS.forEach((attr) => {
+        const value = seen[attr].size === 1
+            ? [...seen[attr]][0]
+            : undefined;
+        if (value)
+            typography[attr] = value;
+    });
+    return typography;
+};
+/**
+ * BP-5969 — build the "reset to role" chain for the whole selection: re-link every typography attr
+ * the role DEFINES to its `var(--role-*)` token (self-describing, follows future role edits), unset
+ * the attrs the role leaves undefined, and clear the legacy semantic marks (bold/italic/underline/
+ * strike) that the attr resets don't touch. Returns the un-run chain so the caller can wrap it in
+ * `skipStyleDetection` (keeping the role link) before running. Colour marks are left alone.
+ */
+export const relinkTypographyChain = (editor, role) => {
+    const chain = editor.chain().selectAll();
+    if (role?.fontFamily)
+        chain.setFontFamily(roleVarRef('fontFamily'));
+    else
+        chain.unsetFontFamily();
+    if (role?.fontSize)
+        chain.setFontSize(roleVarRef('fontSize'));
+    else
+        chain.unsetFontSize();
+    if (role?.lineHeight)
+        chain.setLineHeight(roleVarRef('lineHeight'));
+    else
+        chain.unsetLineHeight();
+    if (role?.letterSpacing)
+        chain.setLetterSpacing(roleVarRef('letterSpacing'));
+    else
+        chain.unsetLetterSpacing();
+    if (role?.fontWeight)
+        chain.setFontWeight(roleVarRef('fontWeight'));
+    else
+        chain.unsetFontWeight();
+    if (role?.fontStyle)
+        chain.setFontStyle(roleVarRef('fontStyle'));
+    else
+        chain.unsetFontStyle();
+    if (role?.textDecoration)
+        chain.setTextDecoration(roleVarRef('textDecoration'));
+    else
+        chain.unsetTextDecoration();
+    return chain
+        .unsetBold()
+        .unsetItalic()
+        .unsetUnderline()
+        .unsetStrike()
+        .command(restoreLinkUnderlines(editor));
+};
+/**
+ * A chain step that puts the underline back on link text that had one before the chain cleared
+ * every underline: a link's underline is its own look, not a typography choice (`typographyAttrsOf`).
+ * Captures the link ranges now, so build it before the chain changes the doc; mark steps keep
+ * positions, so the ranges still hold when it runs.
+ */
+export const restoreLinkUnderlines = (editor) => {
+    const ranges = [];
+    editor.state.doc.descendants((node, pos) => {
+        if (node.isText &&
+            node.marks.some((mark) => mark.type.name === 'link') &&
+            node.marks.some((mark) => mark.type.name === 'underline'))
+            ranges.push([pos, pos + node.nodeSize]);
+    });
+    return ({ tr }) => {
+        const underline = tr.doc.type.schema.marks.underline;
+        if (underline)
+            ranges.forEach(([from, to]) => tr.addMark(from, to, underline.create()));
+        return true;
+    };
+};
+/**
+ * The document-level twin of `relinkTypographyChain`, for a block that isn't being edited: each run's
+ * typography literal that equals any of `roles` (a literal the asterisk never counted as an override)
+ * becomes the `var(--role-*)` ref when `roles[0]` — the role the block links now — defines the attr,
+ * else it's unset. Literals that differ from every role, role refs, colour and link marks are left
+ * alone. Returns the same doc when nothing changes.
+ */
+export const relinkRoleEqualMarks = (doc, roles) => {
+    const [linkedRole] = roles;
+    const clone = JSON.parse(JSON.stringify(doc));
+    let changed = false;
+    const visit = (node) => {
+        const mark = node.marks?.find((m) => m.type === 'textStyle');
+        if (mark?.attrs) {
+            for (const attr of BLOCK_TYPOGRAPHY_ATTRS) {
+                const value = mark.attrs[attr];
+                if (typeof value !== 'string' || value === '' || isRoleVarRef(value))
+                    continue;
+                const equalsARole = roles.some((role) => role &&
+                    normTypographyValue(attr, value) ===
+                        normTypographyValue(attr, role[attr]));
+                if (!equalsARole)
+                    continue;
+                mark.attrs[attr] = linkedRole?.[attr] ? roleVarRef(attr) : null;
+                if (attr === 'textDecoration')
+                    delete mark.attrs.textDecorationReset;
+                changed = true;
+            }
+            if (Object.values(mark.attrs).every((v) => v === null || v === undefined))
+                node.marks = node.marks?.filter((m) => m !== mark);
+        }
+        node.content?.forEach(visit);
+    };
+    visit(clone);
+    return changed ? clone : doc;
+};
+/**
+ * BP-5969 (R19) — the stored-document twin of `relinkTypographyChain`'s reset-to-role chain, for a
+ * doc that isn't mounted in an editor (the AI boundary's role switch). Unlike `relinkRoleEqualMarks`
+ * (which only relinks a literal that already equals a role), every run's typography is reset to
+ * `role` — a deliberate accent override included — mirroring the maker's Reset: a `var(--role-*)`
+ * ref where `role` defines the attr, else unset. The legacy semantic marks (bold/italic/underline/
+ * strike) that the attr resets don't touch are dropped too. Colour and link marks are left alone.
+ *
+ * `styleOverrides` is the call's own surviving style-object override — e.g. a switch call that
+ * also sends `fontFamily: 'Playfair Display'`. Those attrs are nulled, not ref'd: the render fill
+ * (`fillRteRunTypography`) treats a non-null mark value as final, so baking the ref here would bury
+ * the override under it; nulling leaves the render fill free to resolve the literal from the style
+ * object, same as any other block-level override.
+ */
+export const relinkDocToRole = (doc, role, styleOverrides) => {
+    const clone = JSON.parse(JSON.stringify(doc));
+    const visit = (node) => {
+        if (node.type === 'text' && node.marks?.length) {
+            const marks = withoutTypographyMarks(node.marks, BLOCK_TYPOGRAPHY_ATTRS, node.marks.some((mark) => mark.type === 'link'));
+            const textStyle = marks.find((mark) => mark.type === 'textStyle');
+            const attrs = { ...textStyle?.attrs };
+            for (const attr of BLOCK_TYPOGRAPHY_ATTRS) {
+                const override = styleOverrides?.[attr];
+                const isOverridden = typeof override === 'string' &&
+                    override !== '' &&
+                    !isRoleVarRef(override);
+                attrs[attr] = !isOverridden && role?.[attr] ? roleVarRef(attr) : null;
+            }
+            delete attrs.textDecorationReset;
+            // A mark with no colour and every typography attr null (role undefined, or every attr
+            // overridden by a non-role value) carries nothing — drop it rather than leave a no-op
+            // `textStyle` mark behind, same as `relinkRoleEqualMarks` above.
+            const isEmptyMark = Object.values(attrs).every((v) => v === null || v === undefined);
+            if (textStyle) {
+                if (isEmptyMark)
+                    node.marks = marks.filter((m) => m !== textStyle);
+                else {
+                    textStyle.attrs = attrs;
+                    node.marks = marks;
+                }
+            }
+            else if (!isEmptyMark) {
+                marks.push({ type: 'textStyle', attrs });
+                node.marks = marks;
+            }
+            else {
+                node.marks = marks;
+            }
+        }
+        node.content?.forEach(visit);
+    };
+    visit(clone);
+    return clone;
+};
+// The sections the maker mounts an RTE editor on. Derived from the pairs map, but the
+// PLAIN_TEXT_PAIR_SECTIONS are excluded: they appear in the map only for the colour strategy's
+// pairing lookup — their title/description are plain strings whose colour lives on `*.style.color`
+// (rendered by TextWrapper's plain path), so mounting an editor would convert them to a Tiptap doc
+// and strand that colour (the doc renders from the mark, which the plain bake never sets).
+// 'text' has special textItems handling, so it's not in the map but is RTE-enabled.
 export const RTE_ALLOWED_SECTION_TYPES = [
-    ...Object.keys(RTE_SECTION_FIELD_PAIRS),
+    ...Object.keys(RTE_SECTION_FIELD_PAIRS).filter((type) => !PLAIN_TEXT_PAIR_SECTIONS.has(type)),
     'text',
 ];
 export const isRTEManagedStyleField = (sectionType, fieldName) => {
@@ -135,20 +487,6 @@ export const skipStyleDetection = (chain, marks) => chain.command(({ tr }) => {
     }
     return true;
 });
-/**
- * Extract visible plain text from a Tiptap JSON document (concatenated text
- * nodes). Dependency-free — no editor instantiation.
- */
-export const getRteJsonPlainText = (doc) => {
-    const parts = [];
-    const walk = (node) => {
-        if (typeof node.text === 'string')
-            parts.push(node.text);
-        node.content?.forEach(walk);
-    };
-    walk(doc);
-    return parts.join(' ').replace(/\s+/g, ' ').trim();
-};
 // True for RTE content in EITHER shape: a Tiptap JSON document (post-migration)
 // or a legacy inline-HTML string (pre-migration, or a not-yet-migrated site).
 export const hasRTEContent = (content) => isTiptapDocument(content) || isRteHtmlString(content);
@@ -311,280 +649,96 @@ export const replaceTextInRTE = (existingHtml, newText) => {
     return tempDiv.innerHTML;
 };
 /**
- * Whether a rewrap should (re)stamp this linked RTE field, kept in one place so the three
- * structurally-identical rewrap blocks in `transformToRTE` (section field-pairs, the
- * `textItems` loop, and the single-block `text` path) can't drift apart (BP-5886, ADR-0016):
- *  - **type-driven** (a global-style edit): re-stamp existing RTE to propagate the change;
- *  - **store-driven** (section-select / add-content): only convert genuine plain text, so an
- *    already-authored mark (the migration-baked frame colour) is never overwritten on select.
+ * Helper to build stored marks from a style declaration. BP-5969: when `bakeTypography`
+ * is false (a canonical-role block — the class supplies typography), only colour and
+ * highlight are baked; family/size/spacing/line-height/weight/style/decoration are left
+ * to the role class so freshly-typed text follows the role and repaints on a role edit.
  */
-const shouldRewrapRteField = (textStyleType, type, uiStyleSettingsStore, textValue) => !!textStyleType &&
-    (textStyleType === type ||
-        (!!uiStyleSettingsStore && !hasRTEContent(textValue)));
-const transformRTEField = (content, pair, externalEditor, uiStyleSettingsStore, newContent, type, newStyle) => {
-    const fields = content;
-    const style = fields[pair.styleField];
-    const textStyleType = style?.textStyleType;
-    if (shouldRewrapRteField(textStyleType, type, uiStyleSettingsStore, fields[pair.textField])) {
-        let globalContentStyle = uiStyleSettingsStore
-            ? uiStyleSettingsStore.textStyles.textStyleOptions[textStyleType].style
-            : (newStyle ?? {});
-        globalContentStyle = {
-            ...globalContentStyle,
-            textAlign: style?.textAlign,
-            // Element-first colour: a creation-time contrast bake (or a colour picked while
-            // linked) lives on the style field and must survive the rewrap into rich text.
-            // The linked global colour applies only when the element has none — mirroring
-            // `resolveTextColor`'s element-first cascade, so the rewrap can't overpaint the
-            // override with the global colour.
-            color: style?.color || globalContentStyle.color,
-        };
-        fields[pair.textField] = getUpdatedHTMLFromEditor(externalEditor, fields[pair.textField], globalContentStyle);
-    }
-    else if (!textStyleType &&
-        newContent &&
-        newContent.id === content.id &&
-        !hasRTEContent(fields[pair.textField])) {
-        const newContentFields = newContent;
-        const newContentStyle = newContentFields[pair.styleField] ||
-            style;
-        if (newContentStyle) {
-            fields[pair.textField] = getUpdatedHTMLFromEditor(externalEditor, fields[pair.textField], newContentStyle);
-        }
-    }
-};
-const switchRTEField = (content, pair, externalEditor, uiStyleSettingsStore) => {
-    const fields = content;
-    const style = fields[pair.styleField];
-    const textStyleType = style?.textStyleType;
-    if (textStyleType && uiStyleSettingsStore) {
-        let globalContentStyle = uiStyleSettingsStore.textStyles.textStyleOptions[textStyleType].style;
-        globalContentStyle = {
-            ...globalContentStyle,
-            textAlign: style?.textAlign,
-        };
-        if (!hasRTEContent(fields[pair.textField]))
-            fields[pair.textField] = getUpdatedHTMLFromEditor(externalEditor, fields[pair.textField], globalContentStyle);
-    }
-    else if (!textStyleType &&
-        style &&
-        !hasRTEContent(fields[pair.textField])) {
-        fields[pair.textField] = getUpdatedHTMLFromEditor(externalEditor, fields[pair.textField], style);
-    }
-};
-export const transformToRTE = (uiPageSettingStore, externalEditor, uiStyleSettingsStore, newContent, type, newStyle) => {
-    for (const page of uiPageSettingStore.pages) {
-        for (const contentItem of page.contents) {
-            const fieldPairs = RTE_SECTION_FIELD_PAIRS[contentItem.type];
-            if (fieldPairs) {
-                const content = contentItem.settings.content;
-                for (const pair of fieldPairs) {
-                    transformRTEField(content, pair, externalEditor, uiStyleSettingsStore, newContent, type, newStyle);
-                }
-            }
-            if (contentItem.type === 'text') {
-                const textContent = contentItem.settings.content;
-                if (textContent.textItems && textContent.textItems.length > 0) {
-                    for (const [itemIndex, textItemContent,] of textContent.textItems.entries()) {
-                        const textItemStyleType = textItemContent.textStyle.textStyleType;
-                        if (shouldRewrapRteField(textItemStyleType, type, uiStyleSettingsStore, textItemContent.text)) {
-                            let globalContentStyle = uiStyleSettingsStore
-                                ? uiStyleSettingsStore.textStyles.textStyleOptions[textItemStyleType].style
-                                : (newStyle ?? {});
-                            globalContentStyle = {
-                                ...globalContentStyle,
-                                textAlign: textItemContent.textStyle.textAlign,
-                                // Element-first colour — see `transformRTEField`.
-                                color: textItemContent.textStyle.color || globalContentStyle.color,
-                            };
-                            textItemContent.text = getUpdatedHTMLFromEditor(externalEditor, textItemContent.text, globalContentStyle);
-                        }
-                        else if (!textItemStyleType &&
-                            newContent &&
-                            newContent.id === textContent.id &&
-                            !hasRTEContent(textItemContent.text)) {
-                            const newContentStyle = newContent?.textItems?.[itemIndex]
-                                ?.textStyle ?? newContent.textStyle;
-                            textItemContent.text = getUpdatedHTMLFromEditor(externalEditor, textItemContent.text, newContentStyle);
-                        }
-                    }
-                }
-                if ((!textContent.textItems || textContent.textItems.length === 0) &&
-                    textContent.textStyle) {
-                    const textStyleType = textContent.textStyle.textStyleType;
-                    if (shouldRewrapRteField(textStyleType, type, uiStyleSettingsStore, textContent.text)) {
-                        let globalContentStyle = uiStyleSettingsStore
-                            ? uiStyleSettingsStore.textStyles.textStyleOptions[textStyleType]
-                                .style
-                            : (newStyle ?? {});
-                        globalContentStyle = {
-                            ...globalContentStyle,
-                            textAlign: textContent.textStyle.textAlign,
-                            // Element-first colour — see `transformRTEField`.
-                            color: textContent.textStyle.color || globalContentStyle.color,
-                        };
-                        textContent.text = getUpdatedHTMLFromEditor(externalEditor, textContent.text, globalContentStyle);
-                    }
-                    else if (!textStyleType &&
-                        newContent &&
-                        newContent.id === textContent.id &&
-                        !hasRTEContent(textContent.text)) {
-                        const newContentStyle = newContent.textStyle;
-                        textContent.text = getUpdatedHTMLFromEditor(externalEditor, textContent.text, newContentStyle);
-                    }
-                }
-            }
-        }
-    }
-};
-export const switchAllContentToRTE = (uiPageSettingStore, externalEditor, uiStyleSettingsStore) => {
-    for (const page of uiPageSettingStore.pages) {
-        for (const contentItem of page.contents) {
-            const fieldPairs = RTE_SECTION_FIELD_PAIRS[contentItem.type];
-            if (fieldPairs) {
-                const content = contentItem.settings.content;
-                for (const pair of fieldPairs) {
-                    switchRTEField(content, pair, externalEditor, uiStyleSettingsStore);
-                }
-            }
-            if (contentItem.type === 'text') {
-                const textContent = contentItem.settings.content;
-                if (textContent.textItems && textContent.textItems.length > 0) {
-                    for (const [_itemIndex, textItemContent,] of textContent.textItems.entries()) {
-                        const textItemStyleType = textItemContent.textStyle.textStyleType;
-                        if (textItemStyleType && uiStyleSettingsStore) {
-                            let globalContentStyle = uiStyleSettingsStore.textStyles
-                                .textStyleOptions[textItemStyleType]
-                                .style;
-                            globalContentStyle = {
-                                ...globalContentStyle,
-                                textAlign: textItemContent.textStyle.textAlign,
-                            };
-                            if (!hasRTEContent(textItemContent.text))
-                                textItemContent.text = getUpdatedHTMLFromEditor(externalEditor, textItemContent.text, globalContentStyle);
-                        }
-                        else if (!textItemStyleType &&
-                            !hasRTEContent(textItemContent.text)) {
-                            const newContentStyle = textItemContent.textStyle;
-                            textItemContent.text = getUpdatedHTMLFromEditor(externalEditor, textItemContent.text, newContentStyle);
-                        }
-                    }
-                }
-                if ((!textContent.textItems || textContent.textItems.length === 0) &&
-                    textContent.textStyle) {
-                    const textStyleType = textContent.textStyle.textStyleType;
-                    if (textStyleType && uiStyleSettingsStore) {
-                        let globalContentStyle = uiStyleSettingsStore.textStyles
-                            .textStyleOptions[textStyleType].style;
-                        globalContentStyle = {
-                            ...globalContentStyle,
-                            textAlign: textContent.textStyle.textAlign,
-                        };
-                        if (!hasRTEContent(textContent.text))
-                            textContent.text = getUpdatedHTMLFromEditor(externalEditor, textContent.text, globalContentStyle);
-                    }
-                    else if (!textStyleType && !hasRTEContent(textContent.text)) {
-                        const newContentStyle = textContent.textStyle;
-                        textContent.text = getUpdatedHTMLFromEditor(externalEditor, textContent.text, newContentStyle);
-                    }
-                }
-            }
-        }
-    }
-};
-export const getUpdatedHTMLFromEditor = (externalEditor, contentText, newContentStyle) => {
-    if (!contentText) {
-        return contentText;
-    }
-    // BP-5787: accept a string (legacy HTML) or a Tiptap JSON doc. setContent
-    // handles both; only the newline-escaping shim applies to strings.
-    const content = typeof contentText === 'string' &&
-        contentText.includes(ESCAPED_NEWLINE_CHARACTER)
-        ? getRenderText(contentText)
-        : contentText;
-    externalEditor.commands.setContent(content);
-    const currentAlignment = externalEditor.getAttributes(externalEditor.state.selection.$anchor.node().type.name);
-    let chain = externalEditor.chain().selectAll();
-    if (newContentStyle?.fontFamily) {
-        chain = chain.setFontFamily(newContentStyle.fontFamily);
-    }
-    if (newContentStyle?.fontSize) {
-        chain = chain.setFontSize(newContentStyle.fontSize);
-    }
-    if (newContentStyle?.letterSpacing) {
-        chain = chain.setLetterSpacing(newContentStyle.letterSpacing);
-    }
-    if (newContentStyle?.lineHeight) {
-        chain = chain.setLineHeight(newContentStyle.lineHeight);
-    }
-    if (newContentStyle?.color) {
-        chain = chain.setMark('textStyle', {
-            color: getRTEColor(newContentStyle.color, 'text'),
-        });
-    }
-    // Handle backgroundColor
-    if ('backgroundColor' in (newContentStyle || {})) {
-        chain = newContentStyle.backgroundColor
-            ? chain.setMark('highlight', {
-                color: getRTEColor(newContentStyle.backgroundColor, 'background'),
-            })
-            : chain.unsetHighlight();
-    }
-    if (!currentAlignment.textAlign && newContentStyle?.textAlign) {
-        chain = chain.setTextAlign(newContentStyle.textAlign);
-    }
-    const hasStrike = newContentStyle?.textDecoration?.includes('line-through');
-    const hasUnderline = newContentStyle?.textDecoration?.includes('underline');
-    chain = hasStrike ? chain.setStrike() : chain.unsetStrike();
-    chain = hasUnderline ? chain.setUnderline() : chain.unsetUnderline();
-    chain =
-        newContentStyle?.fontWeight === 'bold'
-            ? chain.setBold()
-            : chain.unsetBold();
-    chain = newContentStyle?.fontStyle ? chain.setItalic() : chain.unsetItalic();
-    chain.run();
-    // BP-5787: return the JSON form, consistent with how RTE is now stored.
-    return externalEditor.getJSON();
-};
-// Helper to build stored marks from a style declaration
-export const buildInitialMarks = (state, style) => {
+export const buildInitialMarks = (state, style, bakeTypography = true) => {
     const marks = [];
     const { fontFamily, fontSize, color, lineHeight, letterSpacing, fontWeight, fontStyle, textDecoration, backgroundColor, } = style;
     // TextStyle mark attributes
     const textStyleAttrs = {};
-    if (fontFamily)
-        textStyleAttrs.fontFamily = fontFamily;
-    if (fontSize)
-        textStyleAttrs.fontSize = fontSize;
+    // BP-5969: a canonical-linked block (bakeTypography === false) references the role via
+    // cascade vars — self-describing marks that follow role edits — instead of baking a
+    // literal that would pin the run. Legacy/unlinked bakes the resolved literal as before.
+    // `style` here is the role's resolved style, so the guards write a ref only for the attrs
+    // the role actually defines.
+    if (bakeTypography) {
+        if (fontFamily)
+            textStyleAttrs.fontFamily = fontFamily;
+        if (fontSize)
+            textStyleAttrs.fontSize = fontSize;
+        if (letterSpacing)
+            textStyleAttrs.letterSpacing = letterSpacing;
+        if (lineHeight)
+            textStyleAttrs.lineHeight = lineHeight;
+    }
+    else {
+        if (fontFamily)
+            textStyleAttrs.fontFamily = roleVarRef('fontFamily');
+        if (fontSize)
+            textStyleAttrs.fontSize = roleVarRef('fontSize');
+        if (letterSpacing)
+            textStyleAttrs.letterSpacing = roleVarRef('letterSpacing');
+        if (lineHeight)
+            textStyleAttrs.lineHeight = roleVarRef('lineHeight');
+        // BP-5969 (Phase A): weight/style/decoration are var-backed textStyle attrs too, so newly-typed
+        // linked text follows the role for these as well (not baked as semantic <strong>/<u> marks).
+        if (fontWeight)
+            textStyleAttrs.fontWeight = roleVarRef('fontWeight');
+        if (fontStyle)
+            textStyleAttrs.fontStyle = roleVarRef('fontStyle');
+        if (textDecoration)
+            textStyleAttrs.textDecoration = roleVarRef('textDecoration');
+    }
     if (color) {
         textStyleAttrs.color = getRTEColor(color, 'text');
     }
-    if (letterSpacing)
-        textStyleAttrs.letterSpacing = letterSpacing;
-    if (lineHeight)
-        textStyleAttrs.lineHeight = lineHeight;
-    marks.push(state.schema.marks.textStyle.create(textStyleAttrs));
+    if (Object.keys(textStyleAttrs).length > 0) {
+        marks.push(state.schema.marks.textStyle.create(textStyleAttrs));
+    }
     if (backgroundColor) {
         marks.push(state.schema.marks.highlight.create({
             color: getRTEColor(backgroundColor, 'background'),
         }));
     }
-    // Bold and italic
-    if (fontWeight === 'bold') {
-        marks.push(state.schema.marks.bold.create());
-    }
-    if (fontStyle) {
-        marks.push(state.schema.marks.italic.create());
-    }
-    // Underline and strike-through
-    if (textDecoration?.includes('underline')) {
-        marks.push(state.schema.marks.underline.create());
-    }
-    if (textDecoration?.includes('line-through')) {
-        marks.push(state.schema.marks.strike.create());
+    if (bakeTypography) {
+        // Bold and italic
+        if (fontWeight === 'bold') {
+            marks.push(state.schema.marks.bold.create());
+        }
+        if (fontStyle) {
+            marks.push(state.schema.marks.italic.create());
+        }
+        // Underline and strike-through
+        if (textDecoration?.includes('underline')) {
+            marks.push(state.schema.marks.underline.create());
+        }
+        if (textDecoration?.includes('line-through')) {
+            marks.push(state.schema.marks.strike.create());
+        }
     }
     return marks;
 };
+/**
+ * The first-type seed for an empty field, with what the customer picked before typing laid over it:
+ * a picked mark wins per attribute (its unset attrs keep the seed's), and a picked mark the seed
+ * lacks is added. With nothing picked, the seed as is.
+ */
+export const mergePickedMarks = (seed, picked) => {
+    if (!picked?.length)
+        return [...seed];
+    const merged = seed.map((mark) => {
+        const pick = picked.find((p) => p.type === mark.type);
+        if (!pick)
+            return mark;
+        const pickedAttrs = Object.fromEntries(Object.entries(pick.attrs).filter(([, value]) => value !== null && value !== undefined));
+        return mark.type.create({ ...mark.attrs, ...pickedAttrs });
+    });
+    const added = picked.filter((pick) => !seed.some((mark) => mark.type === pick.type));
+    return [...merged, ...added];
+};
 export const retainStyleOnEmptyLine = (editor, selection) => {
     const { $head } = selection;
     if ($head.parent.content.size === 0) {