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

package/lib/src/brand-page/utils/migration.util.js

@@ -25,6 +25,7 @@ import { migration19 } from './migration/migration-19';
 import { migration20 } from './migration/migration-20';
 import { migration20_5 } from './migration/migration-20_5';
 import { migration21 } from './migration/migration-21';
+import { migration22 } from './migration/migration-22';
 const MIGRATION_TABLE = [
     {
         version: 1,
@@ -195,6 +196,22 @@ const MIGRATION_TABLE = [
         // callers have; see `fillBlankPaletteRoles`.
         description: 'BP-5886 Global Color V2: extract every colour into a central styles.colors palette (4 palette roles + palette-custom-<uuid>) and rewrite references to var(--id) — RTE, shapes, box-shadow, gradients included (lossless, once)',
     },
+    {
+        version: 22,
+        migrateFn: migration22,
+        // Version-gated (runs once, when modelVersion < 22): the BP-5969 single-source
+        // text-style migration (ADR-0019/0020/0021, §7a D1–D5). The 10 roles KEEP their §4
+        // default typography; each old role's COLOUR is seeded onto its target tier so the
+        // colour bake stays byte-identical (paragraph1 takes the base-coat colour). Every
+        // text field (content, nav, header button, Save Contact) outside the ten reconnects
+        // onto its nearest canonical tier, the values that differ from it kept as overrides
+        // so it renders unchanged, and the baked role-typography is stripped out of RTE
+        // marks (uniform-but-divergent values lifted into block overrides, genuine per-run
+        // marks kept). Ordered after v21 so RTE colours are already referencified. The
+        // version gate runs it once; on a hypothetical re-run every job is a no-op (see
+        // migration-22's header).
+        description: 'BP-5969 Global Text Style V2: expand 4 roles -> 10 (H1-6/P1-3/button); roles keep default typography, reconnect all content to its nearest tier with its size kept as a per-block override, seed role colour + strip baked RTE typography (appearance-preserving, once)',
+    },
 ];
 export const GetLatestModelVersion = () => Math.max(...MIGRATION_TABLE.map((x) => x.version));
 export const migrateBrandPageModel = async (brandPageModel, options) => {

package/lib/src/brand-page/utils/model.util.d.ts

@@ -1,3 +1,7 @@
+/**
+ * MIGRATION-22 SNAPSHOT DEPENDENCY: its reconnect and colour bake call `isButtonContent`. After
+ * migration-22 releases, pin its v22 behaviour in the migration before changing it.
+ */
 import { type Content, type AboutSectionContent, type BannerSectionContent, type BrandPageModel, type ButtonWithModalContent, type ImagesSectionContent, type LogoContent, type MailingListContent, type ProfileContent, type ShapesSectionContent, type SocialLinksContent, type SupportMeContent, type TestimonialSectionContent, type TextContent, type RequestPaymentContent, type ContactFormContent, type LogoImageModel, type ShopContent, type ImageContent, type ImageGalleryContent, type BookingSectionContent } from '../models';
 export declare const isLogoContent: (content?: Content) => content is LogoContent;
 export declare const applyLogoImageToBrandPageModelLogoContents: (model: BrandPageModel, logoImage: LogoImageModel) => BrandPageModel;

package/lib/src/brand-page/utils/model.util.js

@@ -1,3 +1,7 @@
+/**
+ * MIGRATION-22 SNAPSHOT DEPENDENCY: its reconnect and colour bake call `isButtonContent`. After
+ * migration-22 releases, pin its v22 behaviour in the migration before changing it.
+ */
 import { CONTENT_TYPES, } from '../models';
 export const isLogoContent = (content) => {
     return content?.type === 'logo';

package/lib/src/brand-page/utils/personalisation.util.js

@@ -1,5 +1,8 @@
 import { escapeContentText } from '@brand-page/utils';
 import { DEFAULT_PERSONALISATION_MAPPING, PERSONALISATION_MAPPINGS, TEXT_MEDIA_CONTENT_TYPES, } from '@brand-page-maker/constants/personalisation.constant';
+// Leaf import, not the `@brand-page-maker/utils` barrel: the barrel would drag the whole maker-utils
+// graph into this brand-page module and risk a cycle (cf. the same guard in section-color-matches.ts).
+import { reflowRteDoc, isTiptapDocument } from '@shared/rte-render.util';
 import { BRAND_PAGE_TYPES, ShapeAspectRatioCategory } from '../models';
 import { getColorReplacementsFromSvgString, getColorReplacementsFromSvgStringServer, } from './svg-color.util';
 const ASPECT_RATIO_LOWER_CUT_OFF = 0.5;
@@ -332,7 +335,12 @@ const applyPersonalisationToBrandPageContentsRecursiveAsync = async (personalisa
                 const { personalisation: updatedPersonalisation, value: personalisationValue, valuesToUpdate: newValuesToUpdate, } = await getPersonalisationValueFromPropertyAsync(key, value, personalisationRole, content[`${key}Override`], newPersonalisation, mappingType);
                 newPersonalisation = updatedPersonalisation;
                 if (personalisationValue) {
-                    newContents[key] = personalisationValue;
+                    // BP-5969: an RTE field is a Tiptap doc whose colour + typography live in its run marks.
+                    // Writing the plain personalisation string raw would drop that style, so reflow the new
+                    // text through the template doc's style skeleton instead; plain/URL fields write raw.
+                    newContents[key] = isTiptapDocument(value)
+                        ? reflowRteDoc(value, personalisationValue)
+                        : personalisationValue;
                     if (newValuesToUpdate) {
                         for (const [k, v] of Object.entries(newValuesToUpdate)) {
                             valuesToUpdate[k] = v;

package/lib/src/brand-page/utils/rte-role-lift.util.d.ts

@@ -0,0 +1,72 @@
+import type { BrandPageModel, TextStyleDeclaration } from '../models';
+import type { TextStyleOptions } from '../models/styles.model';
+/**
+ * Migration-22's job C, shared with the success message seed (`text-role-reconnect.util.ts`): lift an RTE field's block typography onto its
+ * runs once it links a role. A linked run follows the role class unless its mark holds a literal,
+ * and the render fill treats a neutral block value (weight `normal`) as "follow the role" — so
+ * without this a reconnected field can change look (a non-bold title under a bold heading).
+ *
+ * MIGRATION-22 SNAPSHOT DEPENDENCY: this migration consumes the lift and font-vote behaviour. Before
+ * changing it after migration-22 releases, copy the v22 behaviour into that migration first.
+ */
+declare const RTE_TYPOGRAPHY_ATTRS: readonly ["fontFamily", "fontSize", "letterSpacing", "lineHeight"];
+/**
+ * R16 (migration-22 job A2): the distinct fonts a doc's non-empty runs show — a run's own literal
+ * `fontFamily` mark, else the block font (`blockFont`, from `drawnFontFamily`); a `var(--role-*)`
+ * ref counts as the block font too, since it carries no font of its own. A doc whose every run
+ * carries its own literal never adds `blockFont` to the set. Read-only, for the font count only.
+ */
+export declare const textRunFontFamilies: (doc: unknown, blockFont: string) => Set<string>;
+/**
+ * C (BP-5969 role-var model) — bake each RTE field's EFFECTIVE typography onto its run marks. The
+ * container role class now only DEFINES the vars and the element applies nothing, so the block's
+ * typography (previously applied on the element from `styleObj`) and the role must be carried by the
+ * runs themselves, or they'd fall to the body default. For each run and each attr the ROLE defines,
+ * the effective value = per-run mark override ?? block override (`styleObj`) ?? role, stored as:
+ *   • a role ref (`var(--role-<attr>)`) when the effective value EQUALS the role (so it follows role edits), or
+ *   • a literal when it's a genuine override (per-run, or a block-level override from `styleObj`).
+ * Already-referenced values and attrs the role doesn't define are left alone; colour is untouched.
+ * Mutates in place; a non-Tiptap value (legacy HTML string) is skipped. Load-time twin of the
+ * editor's per-run `roleVarOrLiteral` + fill.
+ */
+export declare const stripLiftRteDoc: (doc: unknown, roleStyle: Partial<Record<(typeof RTE_TYPOGRAPHY_ATTRS)[number], string>>, styleObj?: Partial<Record<(typeof RTE_TYPOGRAPHY_ATTRS)[number], string>>) => void;
+/**
+ * C2 (BP-5969 Phase B) — fold the legacy per-run boolean marks (bold/italic/underline/strike) into the
+ * run's `textStyle` attrs (fontWeight/fontStyle/textDecoration), so the whole typography set lives on
+ * ONE mark and follows role edits like the rest. Each formatting mark becomes the matching attr — a
+ * role ref when it equals the role (so a role weight/decoration edit repaints the run), else a literal
+ * override — and the semantic mark is removed. Runs with no formatting mark are left to the render fill
+ * (they follow the role). This is what lets role weight/style/decoration edits reach LEGACY content and
+ * makes the doc self-describing without semantic marks (a prerequisite for retiring the Bold/Underline/
+ * Strike extensions). Mutates in place; a non-Tiptap value is skipped. Runs after `stripLiftRteDoc`
+ * (they touch disjoint attrs — family/size/spacing vs weight/style/decoration).
+ */
+export declare const foldSemanticFormattingMarks: (doc: unknown, roleStyle: Partial<Record<"fontWeight" | "fontStyle" | "textDecoration", string>>) => void;
+/**
+ * C3 (BP-5969) — pin each RTE run's WEIGHT to the block's effective legacy weight, so migrated
+ * content that was NOT bold can't inherit a heading tier's `bold` default. `fontWeight` is the only
+ * role attr with a non-neutral default (headings are bold; style/decoration default to the neutral
+ * `normal`/`none`), so it is the only one that needs this — the render's var-fill treats a block-level
+ * `normal` as inert and would otherwise let the run follow the tier's bold.
+ *
+ * The old roles never set weight, so a legacy run's weight came from its per-run bold mark (already
+ * folded by `foldSemanticFormattingMarks`) or the block's own `fontWeight` — which job B resolved to
+ * `normal` when it was falsy. So for a run the fold left without a weight, bake that block weight as a
+ * LITERAL override whenever it differs from the tier (e.g. `normal` under a bold heading tier). When
+ * block and tier agree, no-op — the render's var-fill already follows the role. Runs after the fold so
+ * a folded bold mark (a genuine per-run weight) is never overwritten. Mutates in place.
+ */
+export declare const pinLegacyRunWeight: (doc: unknown, roleWeight: string | undefined, blockWeight: string | undefined) => void;
+export declare const liftRteFieldOntoRole: (doc: unknown, styleObj: TextStyleDeclaration | undefined, options: TextStyleOptions) => void;
+type RteFieldVisitor = (doc: unknown, styleObj: TextStyleDeclaration | undefined, readStyle: () => TextStyleDeclaration | undefined) => void;
+/**
+ * Every RTE field with its style object: section field-pairs, text `textItems`, and the text
+ * section's single block `text`.
+ */
+export declare const forEachRteField: (brandPageModel: BrandPageModel, visit: RteFieldVisitor) => void;
+/**
+ * C — run the strip/lift over every RTE field. Runs after reconnect so each field's
+ * `textStyleType` is canonical and its role definition is the remapped one.
+ */
+export declare const stripLiftContentRte: (brandPageModel: BrandPageModel, options: TextStyleOptions) => void;
+export {};

package/lib/src/brand-page/utils/rte-role-lift.util.js

@@ -0,0 +1,275 @@
+import { RTE_SECTION_FIELD_PAIRS } from '@shared/color-strategies/rte-field-pairs';
+import { roleVarRef } from './text-role-css.util';
+/**
+ * Migration-22's job C, shared with the success message seed (`text-role-reconnect.util.ts`): lift an RTE field's block typography onto its
+ * runs once it links a role. A linked run follows the role class unless its mark holds a literal,
+ * and the render fill treats a neutral block value (weight `normal`) as "follow the role" — so
+ * without this a reconnected field can change look (a non-bold title under a bold heading).
+ *
+ * MIGRATION-22 SNAPSHOT DEPENDENCY: this migration consumes the lift and font-vote behaviour. Before
+ * changing it after migration-22 releases, copy the v22 behaviour into that migration first.
+ */
+// The role-typography the RTE baked into each run's `textStyle` mark
+// (`getUpdatedHTMLFromEditor` sets exactly these four; colour is also a textStyle
+// attr but is deliberately NOT touched — it stays in the mark).
+const RTE_TYPOGRAPHY_ATTRS = [
+    'fontFamily',
+    'fontSize',
+    'letterSpacing',
+    'lineHeight',
+];
+const collectTextNodes = (node, acc) => {
+    if (!node)
+        return;
+    if (node.type === 'text')
+        acc.push(node);
+    node.content?.forEach((child) => collectTextNodes(child, acc));
+};
+const textStyleMark = (node) => node.marks?.find((mark) => mark.type === 'textStyle');
+/**
+ * R16 (migration-22 job A2): the distinct fonts a doc's non-empty runs show — a run's own literal
+ * `fontFamily` mark, else the block font (`blockFont`, from `drawnFontFamily`); a `var(--role-*)`
+ * ref counts as the block font too, since it carries no font of its own. A doc whose every run
+ * carries its own literal never adds `blockFont` to the set. Read-only, for the font count only.
+ */
+export const textRunFontFamilies = (doc, blockFont) => {
+    const fonts = new Set();
+    if (!doc || typeof doc !== 'object' || doc.type !== 'doc')
+        return fonts;
+    const nodes = [];
+    collectTextNodes(doc, nodes);
+    for (const node of nodes) {
+        if (!node.text || node.text.trim() === '')
+            continue;
+        const literal = textStyleMark(node)?.attrs?.fontFamily;
+        // `''` is FontFamily.ts's "no font of its own" (a colour-only mark parsed from HTML carries
+        // it) — not a literal to vote, so it falls through to the block font like an absent mark.
+        const hasLiteral = typeof literal === 'string' &&
+            literal !== '' &&
+            !literal.startsWith('var(--role-');
+        fonts.add(hasLiteral ? literal : blockFont);
+    }
+    return fonts;
+};
+/**
+ * C (BP-5969 role-var model) — bake each RTE field's EFFECTIVE typography onto its run marks. The
+ * container role class now only DEFINES the vars and the element applies nothing, so the block's
+ * typography (previously applied on the element from `styleObj`) and the role must be carried by the
+ * runs themselves, or they'd fall to the body default. For each run and each attr the ROLE defines,
+ * the effective value = per-run mark override ?? block override (`styleObj`) ?? role, stored as:
+ *   • a role ref (`var(--role-<attr>)`) when the effective value EQUALS the role (so it follows role edits), or
+ *   • a literal when it's a genuine override (per-run, or a block-level override from `styleObj`).
+ * Already-referenced values and attrs the role doesn't define are left alone; colour is untouched.
+ * Mutates in place; a non-Tiptap value (legacy HTML string) is skipped. Load-time twin of the
+ * editor's per-run `roleVarOrLiteral` + fill.
+ */
+export const stripLiftRteDoc = (doc, roleStyle, styleObj) => {
+    if (!doc || typeof doc !== 'object' || doc.type !== 'doc')
+        return;
+    const nodes = [];
+    collectTextNodes(doc, nodes);
+    if (!nodes.length)
+        return;
+    for (const node of nodes) {
+        let mark = textStyleMark(node);
+        for (const attr of RTE_TYPOGRAPHY_ATTRS) {
+            const roleValue = roleStyle?.[attr];
+            // The role doesn't define this attr → the run doesn't carry it (renders `normal`).
+            if (roleValue === undefined || roleValue === null)
+                continue;
+            const ref = roleVarRef(attr);
+            if (!ref)
+                continue;
+            // Ensure a textStyle mark exists to hold the value (a bare run needs one).
+            if (!mark) {
+                mark = { type: 'textStyle', attrs: {} };
+                (node.marks ??= []).push(mark);
+            }
+            if (!mark.attrs)
+                mark.attrs = {};
+            const value = mark.attrs[attr];
+            // already a role ref → keep it
+            if (typeof value === 'string' && value.startsWith('var(--role-'))
+                continue;
+            // per-run override present → re-link if it equals the role, else keep the literal
+            if (value !== undefined && value !== null) {
+                if (value === roleValue)
+                    mark.attrs[attr] = ref;
+                continue;
+            }
+            // no per-run value → bake the block-level effective value: a block-level override
+            // (`styleObj` differs from the role) as a literal — it was applied on the element before and
+            // would be lost now — otherwise the role ref.
+            const blockValue = styleObj?.[attr];
+            mark.attrs[attr] =
+                blockValue !== undefined &&
+                    blockValue !== null &&
+                    blockValue !== roleValue
+                    ? blockValue
+                    : ref;
+        }
+    }
+    // drop textStyle marks left with no attributes (defensive; colour/refs usually remain)
+    for (const node of nodes) {
+        if (!node.marks)
+            continue;
+        node.marks = node.marks.filter((mark) => !(mark.type === 'textStyle' &&
+            (!mark.attrs || Object.keys(mark.attrs).length === 0)));
+    }
+};
+const SEMANTIC_MARK_TYPES = ['bold', 'italic', 'underline', 'strike'];
+/**
+ * C2 (BP-5969 Phase B) — fold the legacy per-run boolean marks (bold/italic/underline/strike) into the
+ * run's `textStyle` attrs (fontWeight/fontStyle/textDecoration), so the whole typography set lives on
+ * ONE mark and follows role edits like the rest. Each formatting mark becomes the matching attr — a
+ * role ref when it equals the role (so a role weight/decoration edit repaints the run), else a literal
+ * override — and the semantic mark is removed. Runs with no formatting mark are left to the render fill
+ * (they follow the role). This is what lets role weight/style/decoration edits reach LEGACY content and
+ * makes the doc self-describing without semantic marks (a prerequisite for retiring the Bold/Underline/
+ * Strike extensions). Mutates in place; a non-Tiptap value is skipped. Runs after `stripLiftRteDoc`
+ * (they touch disjoint attrs — family/size/spacing vs weight/style/decoration).
+ */
+export const foldSemanticFormattingMarks = (doc, roleStyle) => {
+    if (!doc || typeof doc !== 'object' || doc.type !== 'doc')
+        return;
+    const nodes = [];
+    collectTextNodes(doc, nodes);
+    if (!nodes.length)
+        return;
+    const varOrLiteral = (attr, value) => {
+        const ref = roleVarRef(attr);
+        // equal to the role → the role ref (follows role edits); else the literal per-run override
+        return ref && roleStyle?.[attr] === value ? ref : value;
+    };
+    for (const node of nodes) {
+        const marks = node.marks;
+        if (!marks?.length)
+            continue;
+        const has = (type) => marks.some((mark) => mark.type === type);
+        const bold = has('bold');
+        const italic = has('italic');
+        const underline = has('underline');
+        const strike = has('strike');
+        if (!bold && !italic && !underline && !strike)
+            continue;
+        let mark = textStyleMark(node);
+        if (!mark) {
+            mark = { type: 'textStyle', attrs: {} };
+            marks.push(mark);
+        }
+        if (!mark.attrs)
+            mark.attrs = {};
+        // A per-run boolean mark is an explicit override — write it unless a value is already present.
+        if (bold && mark.attrs.fontWeight == null) {
+            mark.attrs.fontWeight = varOrLiteral('fontWeight', 'bold');
+        }
+        if (italic && mark.attrs.fontStyle == null) {
+            mark.attrs.fontStyle = varOrLiteral('fontStyle', 'italic');
+        }
+        if ((underline || strike) && mark.attrs.textDecoration == null) {
+            const decoration = [
+                underline ? 'underline' : '',
+                strike ? 'line-through' : '',
+            ]
+                .filter(Boolean)
+                .join(' ');
+            mark.attrs.textDecoration = varOrLiteral('textDecoration', decoration);
+        }
+        node.marks = marks.filter((mark) => !SEMANTIC_MARK_TYPES.includes(mark.type));
+    }
+};
+/**
+ * C3 (BP-5969) — pin each RTE run's WEIGHT to the block's effective legacy weight, so migrated
+ * content that was NOT bold can't inherit a heading tier's `bold` default. `fontWeight` is the only
+ * role attr with a non-neutral default (headings are bold; style/decoration default to the neutral
+ * `normal`/`none`), so it is the only one that needs this — the render's var-fill treats a block-level
+ * `normal` as inert and would otherwise let the run follow the tier's bold.
+ *
+ * The old roles never set weight, so a legacy run's weight came from its per-run bold mark (already
+ * folded by `foldSemanticFormattingMarks`) or the block's own `fontWeight` — which job B resolved to
+ * `normal` when it was falsy. So for a run the fold left without a weight, bake that block weight as a
+ * LITERAL override whenever it differs from the tier (e.g. `normal` under a bold heading tier). When
+ * block and tier agree, no-op — the render's var-fill already follows the role. Runs after the fold so
+ * a folded bold mark (a genuine per-run weight) is never overwritten. Mutates in place.
+ */
+export const pinLegacyRunWeight = (doc, roleWeight, blockWeight) => {
+    if (!doc || typeof doc !== 'object' || doc.type !== 'doc')
+        return;
+    // Only a genuine override needs a literal: an absent block weight is a non-legacy (canonical)
+    // block, and a block weight equal to the tier is already supplied by the role class — both follow
+    // the role via the render's var-fill.
+    if (blockWeight === undefined ||
+        blockWeight === null ||
+        blockWeight === '' ||
+        blockWeight === roleWeight) {
+        return;
+    }
+    const nodes = [];
+    collectTextNodes(doc, nodes);
+    for (const node of nodes) {
+        let mark = textStyleMark(node);
+        // A per-run weight (a folded bold mark, or an author's per-run edit) is authoritative.
+        const existing = mark?.attrs?.fontWeight;
+        if (existing !== undefined && existing !== null && existing !== '')
+            continue;
+        if (!mark) {
+            mark = { type: 'textStyle', attrs: {} };
+            (node.marks ??= []).push(mark);
+        }
+        if (!mark.attrs)
+            mark.attrs = {};
+        mark.attrs.fontWeight = blockWeight;
+    }
+};
+export const liftRteFieldOntoRole = (doc, styleObj, options) => {
+    const type = styleObj?.textStyleType;
+    if (!type)
+        return;
+    const roleStyle = options[type]?.style;
+    if (roleStyle) {
+        // Pass the block-level style so a block typography override (applied on the element before this
+        // change) is baked onto the runs, not lost now that the element applies nothing. Family/size/
+        // line-height/spacing are baked here; weight is handled by the fold + `pinLegacyRunWeight` below,
+        // style/decoration by the fold — they follow role edits via the cascade otherwise.
+        stripLiftRteDoc(doc, roleStyle, styleObj);
+        // Phase B: fold legacy bold/italic/underline/strike marks into the run's textStyle attrs, so
+        // weight/style/decoration follow role edits on legacy content too and no semantic marks remain.
+        foldSemanticFormattingMarks(doc, roleStyle);
+        // C3: pin a not-bold legacy block's weight so a bold heading tier can't bold its bare runs.
+        pinLegacyRunWeight(doc, roleStyle.fontWeight, styleObj?.fontWeight);
+    }
+};
+/**
+ * Every RTE field with its style object: section field-pairs, text `textItems`, and the text
+ * section's single block `text`.
+ */
+export const forEachRteField = (brandPageModel, visit) => {
+    const visitAt = (holder, textKey, styleKey) => {
+        const readStyle = () => holder[styleKey];
+        visit(holder[textKey], readStyle(), readStyle);
+    };
+    for (const page of brandPageModel.pages ?? []) {
+        for (const content of page.contents ?? []) {
+            const fields = content;
+            const pairs = RTE_SECTION_FIELD_PAIRS[content.type] ?? [];
+            for (const pair of pairs)
+                visitAt(fields, pair.textField, pair.styleField);
+            if (content.type === 'text') {
+                const items = fields.textItems;
+                if (Array.isArray(items)) {
+                    for (const item of items) {
+                        if (item && typeof item === 'object') {
+                            visitAt(item, 'text', 'textStyle');
+                        }
+                    }
+                }
+                visitAt(fields, 'text', 'textStyle');
+            }
+        }
+    }
+};
+/**
+ * C — run the strip/lift over every RTE field. Runs after reconnect so each field's
+ * `textStyleType` is canonical and its role definition is the remapped one.
+ */
+export const stripLiftContentRte = (brandPageModel, options) => forEachRteField(brandPageModel, (doc, styleObj) => liftRteFieldOntoRole(doc, styleObj, options));

package/lib/src/brand-page/utils/style.util.d.ts

@@ -10,7 +10,9 @@ export declare const paletteToCssVarDeclarations: (colors: ColorItem[], options?
  * attribute rather than an `id` so a duplicate stays queryable instead of being invalid HTML.
  */
 export declare const PALETTE_ROOT_ATTRIBUTE = "data-palette-root";
-/** Full `<style>:root{…}</style>` block for `Page`'s `v-html` (standalone surfaces). */
+/** CSS text for Page's stable native style element on standalone surfaces. */
+export declare const buildPaletteRootCssText: (colors: ColorItem[]) => string;
+/** Full `<style>:root{…}</style>` fragment retained for callers outside Page. */
 export declare const buildPaletteRootCss: (colors: ColorItem[]) => string;
 /**
  * Markers for the SCOPED emission (template cards). Unlike `data-palette-root` (≤1 per
@@ -27,6 +29,8 @@ export declare const PAGE_SCOPE_ID_ATTRIBUTE = "data-page-scope";
  * card's block targets its own nodes instead, shadowing the canvas `:root` for its subtree.
  * Role defaults are forced so no role name falls through to the canvas (see `paletteCssEntries`).
  */
+export declare const buildPaletteScopedCssText: (colors: ColorItem[], scopeId: string) => string;
+/** Full scoped `<style>` fragment retained for callers outside Page. */
 export declare const buildPaletteScopedCss: (colors: ColorItem[], scopeId: string) => string;
 /**
  * Simple utility to convert any color format to hex for consistent comparison

package/lib/src/brand-page/utils/style.util.js

@@ -26,15 +26,24 @@ const paletteCssEntries = (colors = [], { forceRoleDefaults = false } = {}) => {
     // the literal text `undefined`.
     const entries = PALETTE_COLOR_ID_ORDER.flatMap((id) => {
         const value = roleValueOrDefault(id, byId.get(id));
-        return value ? [[`--${id}`, value]] : [];
+        return value && isSafePaletteEntry(id, value)
+            ? [[`--${id}`, value]]
+            : [];
     });
     byId.forEach((value, id) => {
-        if (!isPaletteRoleId(id) && !isBlankColorValue(value)) {
+        if (!isPaletteRoleId(id) &&
+            !isBlankColorValue(value) &&
+            isSafePaletteEntry(id, value)) {
             entries.push([`--${id}`, value]);
         }
     });
     return entries;
 };
+// `/` admits the slash alpha form (`rgb(0 0 0 / 50%)`). Without `*` or `<` it can't open a CSS
+// comment or close the style tag.
+const isSafePaletteEntry = (id, value) => /^[a-zA-Z0-9_-]+$/.test(id) &&
+    typeof value === 'string' &&
+    /^[a-zA-Z0-9#(),.%\s/-]+$/.test(value);
 export const paletteToCssVarDeclarations = (colors, options = {}) => paletteCssEntries(colors, options)
     .map(([name, value]) => `${name}: ${value};`)
     .join('\n    ');
@@ -44,14 +53,21 @@ export const paletteToCssVarDeclarations = (colors, options = {}) => paletteCssE
  * attribute rather than an `id` so a duplicate stays queryable instead of being invalid HTML.
  */
 export const PALETTE_ROOT_ATTRIBUTE = 'data-palette-root';
-/** Full `<style>:root{…}</style>` block for `Page`'s `v-html` (standalone surfaces). */
-export const buildPaletteRootCss = (colors) => {
+/** CSS text for Page's stable native style element on standalone surfaces. */
+export const buildPaletteRootCssText = (colors) => {
     const declarations = paletteToCssVarDeclarations(colors);
     return declarations
-        ? `<style ${PALETTE_ROOT_ATTRIBUTE}>
-  :root {
+        ? `:root {
     ${declarations}
-  }
+  }`
+        : '';
+};
+/** Full `<style>:root{…}</style>` fragment retained for callers outside Page. */
+export const buildPaletteRootCss = (colors) => {
+    const css = buildPaletteRootCssText(colors);
+    return css
+        ? `<style ${PALETTE_ROOT_ATTRIBUTE}>
+  ${css}
 </style>`
         : '';
 };
@@ -70,15 +86,22 @@ export const PAGE_SCOPE_ID_ATTRIBUTE = 'data-page-scope';
  * card's block targets its own nodes instead, shadowing the canvas `:root` for its subtree.
  * Role defaults are forced so no role name falls through to the canvas (see `paletteCssEntries`).
  */
-export const buildPaletteScopedCss = (colors, scopeId) => {
+export const buildPaletteScopedCssText = (colors, scopeId) => {
     const declarations = paletteToCssVarDeclarations(colors, {
         forceRoleDefaults: true,
     });
     return declarations && scopeId
-        ? `<style ${PALETTE_SCOPED_ATTRIBUTE}>
-  [${PAGE_SCOPE_ID_ATTRIBUTE}="${scopeId}"] {
+        ? `[${PAGE_SCOPE_ID_ATTRIBUTE}="${scopeId}"] {
     ${declarations}
-  }
+  }`
+        : '';
+};
+/** Full scoped `<style>` fragment retained for callers outside Page. */
+export const buildPaletteScopedCss = (colors, scopeId) => {
+    const css = buildPaletteScopedCssText(colors, scopeId);
+    return css
+        ? `<style ${PALETTE_SCOPED_ATTRIBUTE}>
+  ${css}
 </style>`
         : '';
 };

package/lib/src/brand-page/utils/text-role-css.util.d.ts

@@ -0,0 +1,19 @@
+import type { ComputedRef, InjectionKey } from 'vue';
+import type { JSONContent } from '@tiptap/vue-3';
+import { type GlobalTextStyleDeclaration, type TextStyleOptions } from '../models/styles.model';
+import { type RoleVarMarkAttr } from '@shared/text-role-typography.util';
+export { ROLE_VAR_ATTRS, roleVarRef, runTypographyFillValue, textRoleClassName, type RoleVarMarkAttr, } from '@shared/text-role-typography.util';
+export declare const TEXT_ROLE_OPTIONS_KEY: InjectionKey<ComputedRef<TextStyleOptions | undefined>>;
+export declare const TEXT_ROLE_STYLE_ATTRIBUTE = "data-text-roles";
+export declare const TEXT_ROLE_SCOPED_ATTRIBUTE = "data-text-roles-scoped";
+export declare const roleStyleFor: (type: string | undefined, options: TextStyleOptions | undefined) => GlobalTextStyleDeclaration | undefined;
+export declare const roleClassFor: (type: string | undefined) => string | undefined;
+export declare const cssFontFamilyValue: (value: string) => string;
+export declare const roleTypographyStyle: (own: Partial<Record<RoleVarMarkAttr, string>> | undefined, roleStyle: Partial<Record<RoleVarMarkAttr, string>> | undefined, options?: {
+    omit?: RoleVarMarkAttr[];
+}) => Partial<Record<RoleVarMarkAttr, string>>;
+export declare const fillRteRunTypography: (doc: JSONContent, roleStyle: Partial<Record<RoleVarMarkAttr, string>> | undefined, styleObj: Partial<Record<RoleVarMarkAttr, string>> | undefined) => JSONContent;
+export declare const buildTextRoleRootCssText: (textStyleOptions: TextStyleOptions) => string;
+export declare const buildTextRoleRootCss: (textStyleOptions: TextStyleOptions) => string;
+export declare const buildTextRoleScopedCssText: (textStyleOptions: TextStyleOptions, scopeId: string) => string;
+export declare const buildTextRoleScopedCss: (textStyleOptions: TextStyleOptions, scopeId: string) => string;