@designcrowd/library.brand-page 6.2.11 → 6.2.12

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

@@ -2,47 +2,544 @@ import type { ChainedCommands, Editor, JSONContent } from '@tiptap/vue-3';
 import type { EditorState, Transaction, Selection } from 'prosemirror-state';
 import {
   STYLE_THEME_KEYS,
-  type BannerSectionContent,
-  type BookingSectionContent,
-  type Content,
-  type ImagesSectionContent,
-  type MailingListContent,
-  type ProfileContent,
-  type ShapesSectionContent,
-  type TextContent,
+  CANONICAL_TEXT_STYLE_TYPES,
   type TextStyleDeclaration,
-  type TextStyleType,
-  type ContactFormContent,
-  type AboutSectionContent,
-  type TestimonialSectionContent,
-  type SocialLinksContent,
-  type RequestPaymentContent,
-  type SupportMeContent,
-  type ShopContent,
   type RichTextValue,
 } from '@brand-page';
-import type { PageSettingsState } from '@shared/page-settings/store';
-import type { StyleSettingsState } from '@shared/style-settings/store';
 import { collectRteTextColors } from '@shared/color-strategies/rte-color';
-import { ESCAPED_NEWLINE_CHARACTER } from '@src/constants/ui';
-import { getRenderText } from '@brand-page/utils';
-import type { Mark } from 'prosemirror-model';
+import {
+  composeTextDecoration,
+  localTextDecoration,
+  roleVarRef,
+} from '@shared/text-role-typography.util';
+import type { Mark, Node as ProseMirrorNode } from 'prosemirror-model';
 import createDomPurify, { type DOMPurify } from 'dompurify';
 import Color from 'color';
-import { isHrefPageId } from '../composables/rich-text-editor/hyperlink';
+import { isHrefPageId } from '@shared/rte-link.util';
 import {
   RTE_SECTION_FIELD_PAIRS,
-  type RTEFieldPair,
+  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';
+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: { textStyleType?: string | undefined } | undefined,
+): boolean =>
+  !!style?.textStyleType &&
+  (CANONICAL_TEXT_STYLE_TYPES as readonly string[]).includes(
+    style.textStyleType,
+  );
+
+/** True when a mark value is a role reference (`var(--role-…)`) rather than a literal. */
+export const isRoleVarRef = (value: unknown): value is string =>
+  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: Record<string, string> = {
+  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: string, value?: string): string => {
+  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: string,
+  picked: string,
+  roleStyle: TextStyleDeclaration | undefined,
+): string => {
+  const ref = roleVarRef(markAttr);
+  const roleValue = (roleStyle as Record<string, unknown> | undefined)?.[
+    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',
+] as const;
+
+type BlockTypographyAttr = (typeof BLOCK_TYPOGRAPHY_ATTRS)[number];
+
+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: ProseMirrorNode,
+): readonly BlockTypographyAttr[] =>
+  node.marks.some((mark) => mark.type.name === 'link')
+    ? LINK_TYPOGRAPHY_ATTRS
+    : BLOCK_TYPOGRAPHY_ATTRS;
+
+export const LEGACY_TYPOGRAPHY_MARKS: Partial<
+  Record<BlockTypographyAttr, string[]>
+> = {
+  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 = <M extends { type: string }>(
+  marks: readonly M[],
+  attrs: readonly BlockTypographyAttr[],
+  isLink: boolean,
+): M[] => {
+  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: ProseMirrorNode,
+): Record<BlockTypographyAttr, string | undefined> => {
+  const textStyle = node.marks.find((mark) => mark.type.name === 'textStyle');
+  const attrOf = (attr: string): string | undefined => {
+    const value = textStyle?.attrs?.[attr];
+
+    return typeof value === 'string' && value !== '' ? value : undefined;
+  };
+  const has = (markName: string) =>
+    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: BlockTypographyAttr,
+  value: string | undefined,
+  role: Record<string, unknown>,
+  previousRole?: Record<string, unknown>,
+): value is string =>
+  value !== undefined &&
+  !isRoleVarRef(value) &&
+  normTypographyValue(
+    attr,
+    attr === 'textDecoration'
+      ? composeTextDecoration(
+          previousRole?.textDecoration as string | undefined,
+          value,
+        )
+      : value,
+  ) === normTypographyValue(attr, role[attr] as string | undefined);
+
+/**
+ * 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: Editor,
+  role: Record<string, unknown>,
+): boolean => {
+  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: Editor,
+  role: Record<string, unknown>,
+  previousRole?: Record<string, unknown>,
+): ChainedCommands =>
+  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: Record<string, unknown> = {
+        ...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: Editor): Record<string, string> => {
+  const seen: Record<string, Set<string | undefined>> = Object.fromEntries(
+    BLOCK_TYPOGRAPHY_ATTRS.map((attr) => [attr, new Set<string | undefined>()]),
+  );
+  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: Record<string, string> = {};
+
+  BLOCK_TYPOGRAPHY_ATTRS.forEach((attr) => {
+    const value =
+      seen[attr].size === 1
+        ? ([...seen[attr]][0] as string | undefined)
+        : 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: Editor,
+  role: Record<string, unknown> | undefined,
+): ChainedCommands => {
+  const chain = editor.chain().selectAll();
+
+  if (role?.fontFamily) chain.setFontFamily(roleVarRef('fontFamily') as string);
+  else chain.unsetFontFamily();
+
+  if (role?.fontSize) chain.setFontSize(roleVarRef('fontSize') as string);
+  else chain.unsetFontSize();
+
+  if (role?.lineHeight) chain.setLineHeight(roleVarRef('lineHeight') as string);
+  else chain.unsetLineHeight();
+
+  if (role?.letterSpacing)
+    chain.setLetterSpacing(roleVarRef('letterSpacing') as string);
+  else chain.unsetLetterSpacing();
+
+  if (role?.fontWeight) chain.setFontWeight(roleVarRef('fontWeight') as string);
+  else chain.unsetFontWeight();
+
+  if (role?.fontStyle) chain.setFontStyle(roleVarRef('fontStyle') as string);
+  else chain.unsetFontStyle();
+
+  if (role?.textDecoration)
+    chain.setTextDecoration(roleVarRef('textDecoration') as string);
+  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: Editor,
+): ((props: { tr: Transaction }) => boolean) => {
+  const ranges: [number, number][] = [];
+
+  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;
+  };
+};
+
+type RteRunNode = {
+  type?: string;
+  marks?: { type: string; attrs?: Record<string, unknown> }[];
+  content?: RteRunNode[];
+};
+
+/**
+ * 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: JSONContent,
+  roles: readonly (Record<string, unknown> | undefined)[],
+): JSONContent => {
+  const [linkedRole] = roles;
+  const clone = JSON.parse(JSON.stringify(doc)) as RteRunNode;
+  let changed = false;
+
+  const visit = (node: RteRunNode): void => {
+    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] as string | undefined),
+        );
+
+        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 as JSONContent) : 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: JSONContent,
+  role: Record<string, unknown> | undefined,
+  styleOverrides?: Record<string, unknown>,
+): JSONContent => {
+  const clone = JSON.parse(JSON.stringify(doc)) as RteRunNode;
+
+  const visit = (node: RteRunNode): void => {
+    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: Record<string, unknown> = { ...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);
+  };
 
-export { isTiptapDocument, isRteHtmlString };
+  visit(clone);
 
-// 'text' has special textItems handling, so it's not in the map but is RTE-enabled
+  return clone as JSONContent;
+};
+
+// 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',
 ];
 
@@ -59,22 +556,6 @@ export const isRTEManagedStyleField = (
   return pairs.some((pair) => pair.styleField === fieldName);
 };
 
-// Union of all section content types that support RTE field-pair processing
-type RTESectionContent =
-  | BannerSectionContent
-  | BookingSectionContent
-  | ImagesSectionContent
-  | ShapesSectionContent
-  | MailingListContent
-  | ProfileContent
-  | ContactFormContent
-  | AboutSectionContent
-  | TestimonialSectionContent
-  | SocialLinksContent
-  | RequestPaymentContent
-  | SupportMeContent
-  | ShopContent;
-
 // Only allow tags used by the enabled Tiptap extensions
 const allowedTags = [
   'p',
@@ -202,24 +683,6 @@ export const skipStyleDetection = (chain: ChainedCommands, marks?: Mark[]) =>
     return true;
   });
 
-/**
- * Extract visible plain text from a Tiptap JSON document (concatenated text
- * nodes). Dependency-free — no editor instantiation.
- */
-export const getRteJsonPlainText = (doc: JSONContent): string => {
-  const parts: string[] = [];
-
-  const walk = (node: JSONContent): void => {
-    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: unknown): boolean =>
@@ -429,435 +892,15 @@ export const replaceTextInRTE = (
 };
 
 /**
- * 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: TextStyleType | undefined,
-  type: TextStyleType | undefined,
-  uiStyleSettingsStore: StyleSettingsState | undefined,
-  textValue: unknown,
-): boolean =>
-  !!textStyleType &&
-  (textStyleType === type ||
-    (!!uiStyleSettingsStore && !hasRTEContent(textValue)));
-
-const transformRTEField = (
-  content: RTESectionContent,
-  pair: RTEFieldPair,
-  externalEditor: Editor,
-  uiStyleSettingsStore: StyleSettingsState | undefined,
-  newContent: Content | undefined,
-  type: TextStyleType | undefined,
-  newStyle: TextStyleDeclaration | undefined,
-) => {
-  const fields = content as unknown as Record<string, unknown>;
-  const style = fields[pair.styleField] as TextStyleDeclaration | undefined;
-  const textStyleType = style?.textStyleType;
-
-  if (
-    shouldRewrapRteField(
-      textStyleType,
-      type,
-      uiStyleSettingsStore,
-      fields[pair.textField],
-    )
-  ) {
-    let globalContentStyle = uiStyleSettingsStore
-      ? uiStyleSettingsStore.textStyles.textStyleOptions[textStyleType!].style
-      : (newStyle ?? ({} as TextStyleDeclaration));
-
-    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] as string,
-      globalContentStyle,
-    );
-  } else if (
-    !textStyleType &&
-    newContent &&
-    newContent.id === content.id &&
-    !hasRTEContent(fields[pair.textField] as string)
-  ) {
-    const newContentFields = newContent as unknown as Record<string, unknown>;
-    const newContentStyle =
-      (newContentFields[pair.styleField] as TextStyleDeclaration | undefined) ||
-      style;
-
-    if (newContentStyle) {
-      fields[pair.textField] = getUpdatedHTMLFromEditor(
-        externalEditor,
-        fields[pair.textField] as string,
-        newContentStyle,
-      );
-    }
-  }
-};
-
-const switchRTEField = (
-  content: RTESectionContent,
-  pair: RTEFieldPair,
-  externalEditor: Editor,
-  uiStyleSettingsStore: StyleSettingsState | undefined,
-) => {
-  const fields = content as unknown as Record<string, unknown>;
-  const style = fields[pair.styleField] as TextStyleDeclaration | undefined;
-  const textStyleType = style?.textStyleType;
-
-  if (textStyleType && uiStyleSettingsStore) {
-    let globalContentStyle = uiStyleSettingsStore.textStyles.textStyleOptions[
-      textStyleType
-    ].style as TextStyleDeclaration;
-
-    globalContentStyle = {
-      ...globalContentStyle,
-      textAlign: style?.textAlign,
-    };
-
-    if (!hasRTEContent(fields[pair.textField] as string))
-      fields[pair.textField] = getUpdatedHTMLFromEditor(
-        externalEditor,
-        fields[pair.textField] as string,
-        globalContentStyle,
-      );
-  } else if (
-    !textStyleType &&
-    style &&
-    !hasRTEContent(fields[pair.textField] as string)
-  ) {
-    fields[pair.textField] = getUpdatedHTMLFromEditor(
-      externalEditor,
-      fields[pair.textField] as string,
-      style,
-    );
-  }
-};
-
-export const transformToRTE = (
-  uiPageSettingStore: PageSettingsState,
-  externalEditor: Editor,
-  uiStyleSettingsStore?: StyleSettingsState,
-  newContent?: Content,
-  type?: TextStyleType,
-  newStyle?: TextStyleDeclaration,
-) => {
-  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 as RTESectionContent;
-
-        for (const pair of fieldPairs) {
-          transformRTEField(
-            content,
-            pair,
-            externalEditor,
-            uiStyleSettingsStore,
-            newContent,
-            type,
-            newStyle,
-          );
-        }
-      }
-
-      if (contentItem.type === 'text') {
-        const textContent = contentItem.settings.content as TextContent;
-
-        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 ?? ({} as TextStyleDeclaration));
-
-              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 as TextContent)?.textItems?.[itemIndex]
-                  ?.textStyle ?? (newContent as TextContent).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 ?? ({} as TextStyleDeclaration));
-
-            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 as TextContent).textStyle;
-
-            textContent.text = getUpdatedHTMLFromEditor(
-              externalEditor,
-              textContent.text,
-              newContentStyle,
-            );
-          }
-        }
-      }
-    }
-  }
-};
-
-export const switchAllContentToRTE = (
-  uiPageSettingStore: PageSettingsState,
-  externalEditor: Editor,
-  uiStyleSettingsStore?: StyleSettingsState,
-) => {
-  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 as RTESectionContent;
-
-        for (const pair of fieldPairs) {
-          switchRTEField(content, pair, externalEditor, uiStyleSettingsStore);
-        }
-      }
-
-      if (contentItem.type === 'text') {
-        const textContent = contentItem.settings.content as TextContent;
-
-        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 as TextStyleDeclaration;
-
-              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 as TextStyleDeclaration;
-
-            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: Editor,
-  contentText: RichTextValue,
-  newContentStyle: TextStyleDeclaration,
-) => {
-  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: EditorState,
   style: TextStyleDeclaration,
+  bakeTypography = true,
 ) => {
   const marks: any[] = [];
   const {
@@ -875,19 +918,46 @@ export const buildInitialMarks = (
   // TextStyle mark attributes
   const textStyleAttrs: Record<string, any> = {};
 
-  if (fontFamily) textStyleAttrs.fontFamily = fontFamily;
+  // 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 (fontSize) textStyleAttrs.fontSize = fontSize;
+    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(
@@ -897,27 +967,61 @@ export const buildInitialMarks = (
     );
   }
 
-  // Bold and italic
-  if (fontWeight === 'bold') {
-    marks.push(state.schema.marks.bold.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());
-  }
+    if (fontStyle) {
+      marks.push(state.schema.marks.italic.create());
+    }
 
-  // Underline and strike-through
-  if (textDecoration?.includes('underline')) {
-    marks.push(state.schema.marks.underline.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 (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: readonly Mark[],
+  picked: readonly Mark[] | null | undefined,
+): Mark[] => {
+  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: Editor,
   selection: Selection,