@designcrowd/library.brand-page 6.2.11 → 6.2.12

package/lib/src/lib.js

@@ -33,7 +33,8 @@ export * as brandPageUtils from './brand-page/utils';
 export { getOptimalLogoSize, calculateOptimizedLogoDimensions, applyLogoImageBase64UrlToBrandPageTemplateModel, recalculateLogoContentDimensions, recalculateHeaderLogoSizes, } from './brand-page/utils/logo.util';
 export { sanitizeRTEHtml } from './brand-page-maker/utils';
 // BP-5787: RTE JSON storage boundary helpers (render/normalise/sanitise/extract).
-export { renderRteToHtml, toRteJson, isTiptapDocument, sanitizeRteJson, getRteJsonPlainText, } from './brand-page-maker/utils';
+export { renderRteToHtml, toRteJson, isTiptapDocument, getRteJsonPlainText, } from './shared/rte-render.util';
+export { sanitizeRteJson } from './brand-page-maker/utils';
 export { getPageSlugFromPageTitle } from './brand-page-maker/utils/slug.util';
 // AI-pipeline preview (longclaw per-turn snapshots): web-renderer's
 // /preview/ai-pipeline render page + manifest server route apply the agent's

package/lib/src/metadata-builder/builders/footer-builder.js

@@ -1,7 +1,7 @@
 import {} from '../../brand-page/models';
 import { BaseMetadataBuilder, } from '../models';
 import { FOOTER_CHECKS } from './section-rules/footer.rules';
-import { applyDetachedStyleOverride, normalizeStyleValue, } from './section-field-utils';
+import { applyAiStyle, normalizeStyleValue } from './section-field-utils';
 import { generateItemId, removeItemsByIds, repositionItemByAnchor, } from './item-id-utils';
 const normaliseSocialUrl = (url) => {
     for (const prefix of ['mailto:', 'tel:']) {
@@ -82,9 +82,8 @@ const applyGlobalFooterChanges = (footer, args, textStyleOptions) => {
         footer.copyrightText = args.copyright_text;
     // copyright_text_style is the same text-style object sections use (typography
     // + colour). Normalise each value the way section styles are normalised
-    // (letterSpacing int→em, lineHeight snap, null→''), then detach from the
-    // global preset via the override helper so a single call resolves the preset
-    // and clears textStyleType once — see resolveGlobalPresetIntoStyle (BP-5420).
+    // (letterSpacing int→em, lineHeight snap, null→''), then apply it the way a
+    // section style is: the copyright keeps its role and stores what differs.
     if (args.copyright_text_style) {
         const updates = {};
         for (const [key, value] of Object.entries(args.copyright_text_style)) {
@@ -93,7 +92,7 @@ const applyGlobalFooterChanges = (footer, args, textStyleOptions) => {
                 updates[key] = normalized;
         }
         if (Object.keys(updates).length > 0)
-            footer.copyrightStyle = applyDetachedStyleOverride(footer.copyrightStyle, updates, textStyleOptions);
+            footer.copyrightStyle = applyAiStyle(footer.copyrightStyle, updates, textStyleOptions);
     }
 };
 const applyViewportFooterChanges = (footer, overrides) => {

package/lib/src/metadata-builder/builders/global-role-propagation.d.ts

@@ -0,0 +1,58 @@
+import type { JSONContent } from '@tiptap/vue-3';
+import type { BrandPageModel } from '../../brand-page/models';
+import type { CanonicalTextStyleType, TextStyleOptions } from '../../brand-page/models/styles.model';
+import type { TextStyleOptionStyle } from '../parsers/ai-toolcall-parser';
+/**
+ * Propagation of an AI site-wide text-role change into existing content (R12).
+ *
+ * `tool_update_global_styles` changes a role's own definition — but a run whose
+ * typography was baked as a literal (an inline RTE mark, or a detached `*Style`
+ * override) does not follow that change: the literal wins over the role's CSS
+ * class at render (ADR-0019). This module walks every page's contents, the
+ * header and the footer and relinks every literal of a CHANGED role+property to
+ * the role's `var(--role-…)` reference, so the change reaches content the pipeline
+ * never re-sends. Unlike the maker's own "apply changes to all" (which only
+ * relinks a literal that already EQUALS the role — genuine overrides are left
+ * alone, ADR-0021), an AI site-wide ask relinks EVERY literal, accent words
+ * included; the one exception is a run or plain field the user named in
+ * `textStyles.keepRuns` (R16).
+ *
+ * All 7 role typography properties relink. Family, size, line height and letter
+ * spacing relink only when the sent value differs from the stored role: the
+ * pipeline re-sends them unchanged, and relinking then would erase accents.
+ * Weight, style and decoration relink on ANY sent value: the pipeline sends them
+ * only when the user asked, and migration-22 pinned literals (`fontWeight:
+ * 'normal'` under a bold heading role) that an equal value must still reach.
+ * They also drop the legacy `<strong>`/`<em>`/`<u>`/`<s>` marks that would win
+ * over the ref; a link keeps its underline.
+ *
+ * Both migrated Tiptap JSON and legacy HTML strings are handled because older sites can still
+ * carry the latter; leaving either shape unchanged would make role edits surface-dependent.
+ *
+ * A field's role comes from its own `textStyleType` — never guessed from the
+ * field name. Every field the metadata-builder touches carries a canonical role
+ * post-migration (the legacy→canonical gate is a hard one, `legacy-migrations.md`),
+ * so no detached/legacy fallback is needed here.
+ */
+/** The 7 role typography properties (ROLE_VAR_ATTRS) a site-wide change relinks. */
+export declare const ROLE_PROPAGATION_ATTRS: readonly ["fontFamily", "fontSize", "lineHeight", "letterSpacing", "fontWeight", "fontStyle", "textDecoration"];
+export type RolePropagationAttr = (typeof ROLE_PROPAGATION_ATTRS)[number];
+export declare const ROLE_VAR_REF: Readonly<Record<RolePropagationAttr, string>>;
+export type ChangedRoleProps = Partial<Record<CanonicalTextStyleType, Partial<Record<RolePropagationAttr, string>>>>;
+/**
+ * Extract the changed canonical roles + properties from a RESOLVED (canonical-only)
+ * `textStyleOptions` merge — the caller (`GlobalStylesBuilder`) has already redirected any
+ * retired key onto its successor role(s) (R7) before calling this.
+ */
+export declare const collectChangedRoleProps: (textStyleOptions: Partial<Record<CanonicalTextStyleType, {
+    style?: TextStyleOptionStyle;
+}>> | undefined, existingOptions?: TextStyleOptions) => ChangedRoleProps;
+/**
+ * Force every literal of a changed attr on every run to its role ref, accent words included, and
+ * drop the legacy marks that compete with it. A ref already in place is left alone ("refs stay");
+ * a run named in `keepRuns` is untouched.
+ */
+export declare const relinkRoleChangedMarks: (doc: JSONContent, changedAttrs: readonly RolePropagationAttr[], keepRuns: readonly string[] | undefined) => JSONContent;
+/** Rewrites a legacy RTE HTML string's marks to the given role refs. Injectable for tests. */
+export type ApplyRoleRefsToRTE = (html: string, refs: Partial<Record<RolePropagationAttr, string>>, keepRuns?: readonly string[]) => string;
+export declare const propagateRolePropsToContents: (model: BrandPageModel, changed: ChangedRoleProps, keepRuns?: readonly string[], applyRefs?: ApplyRoleRefsToRTE) => void;

package/lib/src/metadata-builder/builders/global-role-propagation.js

@@ -0,0 +1,246 @@
+import { CANONICAL_TEXT_STYLE_TYPES } from '../../brand-page/models/styles.model';
+import { NEUTRAL_TYPOGRAPHY_VALUE, roleVarRef, textDecorationFlags, } from '@shared/text-role-typography.util';
+import { hasRTEContent, getPlainTextFromRTE, withoutTypographyMarks, } from '../../brand-page-maker/utils';
+import { useExternalRichTextEditor } from '../../brand-page-maker/composables/rich-text-editor/useRichTextEditor';
+import { applyStyleToRTEText } from '../helpers/rte.helpers';
+import { isTiptapDocument } from '../parsers/section-tool-arguments';
+/**
+ * Propagation of an AI site-wide text-role change into existing content (R12).
+ *
+ * `tool_update_global_styles` changes a role's own definition — but a run whose
+ * typography was baked as a literal (an inline RTE mark, or a detached `*Style`
+ * override) does not follow that change: the literal wins over the role's CSS
+ * class at render (ADR-0019). This module walks every page's contents, the
+ * header and the footer and relinks every literal of a CHANGED role+property to
+ * the role's `var(--role-…)` reference, so the change reaches content the pipeline
+ * never re-sends. Unlike the maker's own "apply changes to all" (which only
+ * relinks a literal that already EQUALS the role — genuine overrides are left
+ * alone, ADR-0021), an AI site-wide ask relinks EVERY literal, accent words
+ * included; the one exception is a run or plain field the user named in
+ * `textStyles.keepRuns` (R16).
+ *
+ * All 7 role typography properties relink. Family, size, line height and letter
+ * spacing relink only when the sent value differs from the stored role: the
+ * pipeline re-sends them unchanged, and relinking then would erase accents.
+ * Weight, style and decoration relink on ANY sent value: the pipeline sends them
+ * only when the user asked, and migration-22 pinned literals (`fontWeight:
+ * 'normal'` under a bold heading role) that an equal value must still reach.
+ * They also drop the legacy `<strong>`/`<em>`/`<u>`/`<s>` marks that would win
+ * over the ref; a link keeps its underline.
+ *
+ * Both migrated Tiptap JSON and legacy HTML strings are handled because older sites can still
+ * carry the latter; leaving either shape unchanged would make role edits surface-dependent.
+ *
+ * A field's role comes from its own `textStyleType` — never guessed from the
+ * field name. Every field the metadata-builder touches carries a canonical role
+ * post-migration (the legacy→canonical gate is a hard one, `legacy-migrations.md`),
+ * so no detached/legacy fallback is needed here.
+ */
+/** The 7 role typography properties (ROLE_VAR_ATTRS) a site-wide change relinks. */
+export const ROLE_PROPAGATION_ATTRS = [
+    'fontFamily',
+    'fontSize',
+    'lineHeight',
+    'letterSpacing',
+    'fontWeight',
+    'fontStyle',
+    'textDecoration',
+];
+export const ROLE_VAR_REF = Object.fromEntries(ROLE_PROPAGATION_ATTRS.map((attr) => [attr, roleVarRef(attr)]));
+// Relink on any sent value, even one equal to the stored role (see the header).
+const EMPHASIS_ATTRS = new Set([
+    'fontWeight',
+    'fontStyle',
+    'textDecoration',
+]);
+const isPlainObject = (v) => !!v && typeof v === 'object' && !Array.isArray(v);
+const isCanonicalRole = (v) => typeof v === 'string' &&
+    CANONICAL_TEXT_STYLE_TYPES.includes(v);
+const isKeptText = (text, keepRuns) => {
+    if (!keepRuns?.length)
+        return false;
+    const trimmed = text.trim().toLowerCase();
+    return keepRuns.some((run) => run.trim().toLowerCase() === trimmed);
+};
+const normalizedRoleValue = (value, attr) => {
+    if (typeof value === 'string' && value.trim())
+        return value.trim();
+    return Object.prototype.hasOwnProperty.call(NEUTRAL_TYPOGRAPHY_VALUE, attr)
+        ? NEUTRAL_TYPOGRAPHY_VALUE[attr]
+        : undefined;
+};
+// One value can be written several ways ('3.0em' / '3em', a quoted family). Comparing the
+// written form would read an unchanged value as a change and relink every word that overrides it.
+const comparableValue = (attr, value) => {
+    if (attr === 'fontFamily')
+        return value.replace(/['"]/g, '').trim();
+    const numeric = /^(-?(?:\d+\.?\d*|\.\d+))([a-z%]*)$/i.exec(value);
+    return numeric
+        ? `${Number(numeric[1])}${numeric[2].toLowerCase()}`
+        : value.toLowerCase();
+};
+/**
+ * Extract the changed canonical roles + properties from a RESOLVED (canonical-only)
+ * `textStyleOptions` merge — the caller (`GlobalStylesBuilder`) has already redirected any
+ * retired key onto its successor role(s) (R7) before calling this.
+ */
+export const collectChangedRoleProps = (textStyleOptions, existingOptions = {}) => {
+    const changed = {};
+    if (!textStyleOptions)
+        return changed;
+    for (const role of CANONICAL_TEXT_STYLE_TYPES) {
+        const style = textStyleOptions[role]?.style;
+        if (!style)
+            continue;
+        const props = {};
+        const existing = existingOptions[role]?.style;
+        for (const attr of ROLE_PROPAGATION_ATTRS) {
+            const value = style[attr];
+            const replacement = typeof value === 'string' && value.trim()
+                ? value.trim()
+                : (value === null || value === '') &&
+                    Object.prototype.hasOwnProperty.call(NEUTRAL_TYPOGRAPHY_VALUE, attr)
+                    ? NEUTRAL_TYPOGRAPHY_VALUE[attr]
+                    : undefined;
+            if (replacement === undefined)
+                continue;
+            if (EMPHASIS_ATTRS.has(attr)) {
+                props[attr] = replacement;
+                continue;
+            }
+            const stored = normalizedRoleValue(existing?.[attr], attr);
+            if (stored === undefined ||
+                comparableValue(attr, replacement) !== comparableValue(attr, stored)) {
+                props[attr] = replacement;
+            }
+        }
+        if (Object.keys(props).length)
+            changed[role] = props;
+    }
+    return changed;
+};
+/**
+ * Force every literal of a changed attr on every run to its role ref, accent words included, and
+ * drop the legacy marks that compete with it. A ref already in place is left alone ("refs stay");
+ * a run named in `keepRuns` is untouched.
+ */
+export const relinkRoleChangedMarks = (doc, changedAttrs, keepRuns) => {
+    const clone = JSON.parse(JSON.stringify(doc));
+    const decorationChanged = changedAttrs.includes('textDecoration');
+    const visit = (node) => {
+        if (node.type === 'text' && node.text && !isKeptText(node.text, keepRuns)) {
+            const mark = node.marks?.find((m) => m.type === 'textStyle');
+            const isLink = !!node.marks?.some((m) => m.type === 'link');
+            // Migration-22 folded a link's `<u>` into this literal; relinking it must keep the link's look.
+            const keepsLinkUnderline = isLink &&
+                decorationChanged &&
+                textDecorationFlags(mark?.attrs?.textDecoration).has('underline');
+            changedAttrs.forEach((attr) => {
+                const value = mark?.attrs?.[attr];
+                if (typeof value === 'string' &&
+                    value &&
+                    value !== ROLE_VAR_REF[attr]) {
+                    mark.attrs[attr] = ROLE_VAR_REF[attr];
+                }
+            });
+            if (decorationChanged)
+                delete mark?.attrs?.textDecorationReset;
+            if (node.marks) {
+                node.marks = withoutTypographyMarks(node.marks, changedAttrs, isLink);
+                if (keepsLinkUnderline &&
+                    !node.marks.some((m) => m.type === 'underline')) {
+                    node.marks.push({ type: 'underline' });
+                }
+            }
+        }
+        node.content?.forEach(visit);
+    };
+    visit(clone);
+    return clone;
+};
+const dropStyleOverrides = (style, changedAttrs) => {
+    changedAttrs.forEach((attr) => {
+        if (attr in style)
+            delete style[attr];
+    });
+};
+const refsFor = (changedAttrs) => Object.fromEntries(changedAttrs.map((attr) => [attr, ROLE_VAR_REF[attr]]));
+const walkRecord = (record, changed, keepRuns, applyRefs) => {
+    for (const [key, value] of Object.entries(record)) {
+        let handled = false;
+        if (key.endsWith('Style') && isPlainObject(value)) {
+            const role = value.textStyleType;
+            if (isCanonicalRole(role) && changed[role]) {
+                handled = true;
+                const changedAttrs = Object.keys(changed[role]);
+                if (key === 'defaultButtonStyle' &&
+                    isPlainObject(record.selectedButtonStyle)) {
+                    dropStyleOverrides(record.selectedButtonStyle, changedAttrs);
+                }
+                const fieldBase = key.slice(0, -'Style'.length);
+                const textKey = fieldBase in record
+                    ? fieldBase
+                    : `${fieldBase}Text` in record
+                        ? `${fieldBase}Text`
+                        : undefined;
+                const textValue = textKey ? record[textKey] : undefined;
+                if (isTiptapDocument(textValue)) {
+                    record[textKey] = relinkRoleChangedMarks(textValue, changedAttrs, keepRuns);
+                    dropStyleOverrides(value, changedAttrs);
+                }
+                else if (typeof textValue === 'string' && hasRTEContent(textValue)) {
+                    if (!isKeptText(getPlainTextFromRTE(textValue), keepRuns)) {
+                        record[textKey] = applyRefs(textValue, refsFor(changedAttrs), keepRuns);
+                        dropStyleOverrides(value, changedAttrs);
+                    }
+                }
+                else {
+                    const plainText = typeof textValue === 'string' ? textValue : undefined;
+                    if (plainText === undefined || !isKeptText(plainText, keepRuns)) {
+                        dropStyleOverrides(value, changedAttrs);
+                    }
+                }
+            }
+        }
+        if (handled)
+            continue;
+        if (Array.isArray(value)) {
+            value.forEach((item) => isPlainObject(item) && walkRecord(item, changed, keepRuns, applyRefs));
+        }
+        else if (isPlainObject(value)) {
+            walkRecord(value, changed, keepRuns, applyRefs);
+        }
+    }
+};
+export const propagateRolePropsToContents = (model, changed, keepRuns, applyRefs) => {
+    if (!Object.keys(changed).length)
+        return;
+    let editor;
+    const apply = applyRefs ??
+        ((text, refs) => {
+            editor = editor ?? useExternalRichTextEditor().externalEditor;
+            return applyStyleToRTEText(editor, text, refs, keepRuns);
+        });
+    try {
+        for (const page of model.pages) {
+            for (const content of page.contents) {
+                walkRecord(content, changed, keepRuns, apply);
+            }
+        }
+        if (model.pageHeaderDesktop) {
+            walkRecord(model.pageHeaderDesktop, changed, keepRuns, apply);
+        }
+        if (model.pageHeaderMobile) {
+            walkRecord(model.pageHeaderMobile, changed, keepRuns, apply);
+        }
+        if (model.pageFooterDesktop) {
+            walkRecord(model.pageFooterDesktop, changed, keepRuns, apply);
+        }
+        if (model.pageFooterMobile) {
+            walkRecord(model.pageFooterMobile, changed, keepRuns, apply);
+        }
+    }
+    finally {
+        editor?.destroy();
+    }
+};

package/lib/src/metadata-builder/builders/global-styles-builder.d.ts

@@ -9,6 +9,7 @@ export declare class GlobalStylesBuilder extends BaseMetadataBuilder<UpdateGloba
     }>;
     buildAsync(model: BrandPageModel): Promise<BuilderResult>;
     private applyTextStyles;
+    private applyTextStylesWarnings;
     private applyButtonStyles;
     private applyBackgroundStyles;
     private mergeStyleOptionStyle;

package/lib/src/metadata-builder/builders/global-styles-builder.js

@@ -1,8 +1,68 @@
 import {} from '../../brand-page/models';
 import { BaseMetadataBuilder, } from '../models';
-import { GLOBAL_STYLE_CHECKS, TEXT_STYLE_OPTION_KEYS, } from './section-rules/global-styles.rules';
-import { collectChangedFontFamilies, propagateFontFamiliesToContents, } from './global-font-propagation';
+import { CANONICAL_TEXT_STYLE_TYPES, LEGACY_TEXT_STYLE_TYPES, } from '../../brand-page/models/styles.model';
+import { computeLegacyTargets, HEADING_TIERS, PARAGRAPH_TIERS, } from '../../brand-page/utils/text-role-reconnect.util';
+import { TEXT_STYLE_CASCADE_PROPS, } from '../../brand-page/utils/text-style.util';
+import { NEUTRAL_TYPOGRAPHY_VALUE } from '@shared/text-role-typography.util';
+import { GLOBAL_STYLE_CHECKS, normalizeGlobalTextStyleOption, } from './section-rules/global-styles.rules';
+import { collectChangedRoleProps, propagateRolePropsToContents, } from './global-role-propagation';
 import { buttonStylePresetCss } from '../../shared/style-settings/button-style-preset';
+const retiredKeyFamilyTiers = (key) => {
+    switch (key) {
+        case 'headings':
+            return HEADING_TIERS.filter((tier) => tier !== 'heading1');
+        case 'paragraphs':
+            return PARAGRAPH_TIERS;
+        case 'titles':
+        case 'buttons':
+            return [];
+    }
+};
+const retiredKeySingleTarget = (key, existingOptions) => computeLegacyTargets(existingOptions)[key];
+const resolveCanonicalTextStyleOptions = (textStyleOptions, existingOptions) => {
+    const resolved = {};
+    if (!textStyleOptions)
+        return resolved;
+    const mergeInto = (role, optionArgs) => {
+        resolved[role] = {
+            style: {
+                ...resolved[role]?.style,
+                ...(optionArgs.style
+                    ? normalizeGlobalTextStyleOption(optionArgs.style)
+                    : undefined),
+            },
+            isModified: optionArgs.isModified ?? resolved[role]?.isModified,
+        };
+    };
+    for (const role of CANONICAL_TEXT_STYLE_TYPES) {
+        const optionArgs = textStyleOptions[role];
+        if (optionArgs)
+            mergeInto(role, optionArgs);
+    }
+    for (const key of LEGACY_TEXT_STYLE_TYPES) {
+        const optionArgs = textStyleOptions[key];
+        if (!optionArgs)
+            continue;
+        const singleTarget = retiredKeySingleTarget(key, existingOptions);
+        const familyTiers = retiredKeyFamilyTiers(key);
+        const style = (optionArgs.style ?? {});
+        const { fontFamily, ...rest } = style;
+        const hasRest = Object.keys(rest).length > 0;
+        if (hasRest || !familyTiers.length || optionArgs.isModified !== undefined) {
+            mergeInto(singleTarget, {
+                style: (familyTiers.length ? rest : style),
+                isModified: optionArgs.isModified,
+            });
+        }
+        if (fontFamily !== undefined && familyTiers.length) {
+            familyTiers.forEach((role) => mergeInto(role, {
+                style: { fontFamily },
+                isModified: optionArgs.isModified,
+            }));
+        }
+    }
+    return resolved;
+};
 export class GlobalStylesBuilder extends BaseMetadataBuilder {
     constructor(request, logger) {
         super(request, logger);
@@ -17,32 +77,36 @@ export class GlobalStylesBuilder extends BaseMetadataBuilder {
             return { errors };
         }
         catch (error) {
+            // Fail closed: a throwing check must block the call, not pass it as clean with every
+            // check skipped.
             this.log({
-                message: 'Global styles validation failed unexpectedly — skipping',
+                message: 'Global styles validation failed unexpectedly — rejecting the call',
                 error,
             });
-            return { errors: [] };
+            return { errors: ['Global styles validation failed unexpectedly'] };
         }
     }
     async buildAsync(model) {
         this.log('Build called');
+        const validation = await this.validateAsync();
+        if (validation.errors.length) {
+            return { request: this.request, model, errors: validation.errors };
+        }
         const args = this.request.payload ?? {};
+        let builderWarnings;
         if (args.backgroundStyles) {
             this.applyBackgroundStyles(model, args.backgroundStyles);
         }
         if (args.textStyles) {
-            this.applyTextStyles(model, args.textStyles);
-            // A category font change only reaches preset-bound content by itself;
-            // detached section styles and inline RTE font marks would still render
-            // the old family. Propagate so the change is actually visible (BP-5780).
-            const changedFamilies = collectChangedFontFamilies(args.textStyles);
-            if (Object.keys(changedFamilies).length) {
+            const { changedRoleProps, warnings } = this.applyTextStyles(model, args.textStyles);
+            builderWarnings = warnings.length ? warnings : undefined;
+            if (Object.keys(changedRoleProps).length) {
                 try {
-                    propagateFontFamiliesToContents(model, changedFamilies);
+                    propagateRolePropsToContents(model, changedRoleProps, args.textStyles.keepRuns);
                 }
                 catch (error) {
                     this.log({
-                        message: 'Global font propagation to existing contents failed — presets still updated',
+                        message: 'Global role propagation to existing contents failed — presets still updated',
                         error,
                     });
                 }
@@ -51,49 +115,50 @@ export class GlobalStylesBuilder extends BaseMetadataBuilder {
         if (args.buttonStyles) {
             this.applyButtonStyles(model, args.buttonStyles);
         }
-        return { request: this.request, model };
+        return { request: this.request, model, warnings: builderWarnings };
     }
     applyTextStyles(model, textStyles) {
         const ts = model.styles.textStyles;
-        // A `textStyles.style` arg is ignored — the property is retired. Schema cleanup
-        // in service.ai-pipelines is a follow-up.
-        // Merge textFontFamily
-        if (textStyles.textFontFamily !== undefined) {
-            ts.textFontFamily = textStyles.textFontFamily;
-        }
-        // Deep-merge textStyleOptions per category
-        if (textStyles.textStyleOptions) {
-            for (const key of TEXT_STYLE_OPTION_KEYS) {
-                const optionArgs = textStyles.textStyleOptions[key];
-                if (!optionArgs)
-                    continue;
-                const existing = ts.textStyleOptions[key];
-                if (!existing)
-                    continue;
-                if (optionArgs.style) {
-                    this.mergeStyleOptionStyle(existing.style, optionArgs.style);
-                    // Mark as modified when style properties change
-                    existing.isModified = true;
-                }
-                if (optionArgs.isModified !== undefined) {
-                    existing.isModified = optionArgs.isModified;
-                }
+        const resolved = resolveCanonicalTextStyleOptions(textStyles.textStyleOptions, ts.textStyleOptions);
+        const changedRoleProps = collectChangedRoleProps(resolved, ts.textStyleOptions);
+        for (const role of CANONICAL_TEXT_STYLE_TYPES) {
+            const optionArgs = resolved[role];
+            if (!optionArgs)
+                continue;
+            const existing = ts.textStyleOptions[role];
+            if (!existing)
+                continue;
+            if (optionArgs.style) {
+                this.mergeStyleOptionStyle(existing.style, optionArgs.style);
+                existing.isModified = true;
+            }
+            if (optionArgs.isModified !== undefined) {
+                existing.isModified = optionArgs.isModified;
             }
         }
+        return {
+            changedRoleProps,
+            warnings: this.applyTextStylesWarnings(textStyles),
+        };
+    }
+    applyTextStylesWarnings(textStyles) {
+        const droppedRoles = Object.entries(textStyles.textStyleOptions ?? {})
+            .filter(([, option]) => option?.style?.color)
+            .map(([role]) => role);
+        return droppedRoles.length
+            ? [
+                `Ignored role color for ${droppedRoles.join(', ')}; apply colour to the affected sections instead.`,
+            ]
+            : [];
     }
     applyButtonStyles(model, buttonStyles) {
         const bs = model.styles.buttonStyles;
-        // Deep-merge style (color, borderColor, backgroundColor)
         if (buttonStyles.style) {
             bs.style = { ...bs.style, ...buttonStyles.style };
         }
-        // Deep-merge iconStyle (fill)
         if (buttonStyles.iconStyle) {
             bs.iconStyle = { ...bs.iconStyle, ...buttonStyles.iconStyle };
         }
-        // Merge selectedButtonStyleId and apply that preset's shape and shadow the way the
-        // editor's picker does: the site renders buttons from `style`, so the id alone is
-        // invisible (BP-6082). The preset owns the shape keys; colours from `style` stay.
         if (buttonStyles.selectedButtonStyleId !== undefined) {
             bs.selectedButtonStyleId = buttonStyles.selectedButtonStyleId;
             const presetCss = buttonStylePresetCss(buttonStyles.selectedButtonStyleId, bs.style);
@@ -135,21 +200,27 @@ export class GlobalStylesBuilder extends BaseMetadataBuilder {
                 bs.backgroundShapes = [];
             }
             else if (bs.backgroundShapes?.length) {
-                // Only update when shapes already exist — never add shapes to a site that has none.
-                // Update ALL shapes so every positional instance switches to the new shape type.
+                // Retype only the shapes a site already has: a site with none never gains one.
                 bs.backgroundShapes = bs.backgroundShapes.map((shape) => ({
                     ...shape,
                     name: backgroundStyles.backgroundShapeUrl,
                 }));
             }
-            // If backgroundShapes is empty/absent: intentional no-op
         }
     }
     mergeStyleOptionStyle(existing, incoming) {
         for (const [key, value] of Object.entries(incoming)) {
-            if (value !== undefined) {
+            if (!TEXT_STYLE_CASCADE_PROPS.includes(key)) {
+                continue;
+            }
+            if (value !== undefined && value !== null && value !== '') {
                 existing[key] = value;
             }
+            else if ((value === null || value === '') &&
+                Object.prototype.hasOwnProperty.call(NEUTRAL_TYPOGRAPHY_VALUE, key)) {
+                existing[key] =
+                    NEUTRAL_TYPOGRAPHY_VALUE[key];
+            }
         }
     }
 }

package/lib/src/metadata-builder/builders/header-builder.js

@@ -2,7 +2,8 @@ import {} from '../../brand-page/models';
 import { BaseMetadataBuilder, } from '../models';
 import { getPageSlugFromPageTitle } from '../../brand-page-maker/utils/slug.util';
 import { HEADER_CHECKS } from './section-rules/header.rules';
-import { applyDetachedStyleOverride } from './section-field-utils';
+import { applyAiStyle } from './section-field-utils';
+import { omitTypography, pickTypography, } from '../../brand-page/utils/text-style.util';
 const applyViewportHeaderChanges = (header, overrides, textStyleOptions) => {
     if (overrides.display_style !== undefined) {
         header.displayStyle = overrides.display_style;
@@ -32,15 +33,23 @@ const applyViewportHeaderChanges = (header, overrides, textStyleOptions) => {
         };
     }
     if (overrides.link_text_font !== undefined && header.navigation) {
-        header.navigation.defaultButtonStyle = applyDetachedStyleOverride(header.navigation.defaultButtonStyle, { fontFamily: overrides.link_text_font }, textStyleOptions);
+        header.navigation.defaultButtonStyle = applyAiStyle(header.navigation.defaultButtonStyle, { fontFamily: overrides.link_text_font }, textStyleOptions, { startingRole: 'paragraph1' });
     }
     // The hamburger overlay renders the same nav links from its own styles, so the
     // menu font has to reach them too or the overlay keeps the old family (BP-6079).
     if (overrides.link_text_font !== undefined &&
         header.navigation?.hamburgerMenuStyle) {
         const menu = header.navigation.hamburgerMenuStyle;
-        menu.defaultButtonStyle = applyDetachedStyleOverride(menu.defaultButtonStyle, { fontFamily: overrides.link_text_font }, textStyleOptions);
-        menu.selectedButtonStyle = applyDetachedStyleOverride(menu.selectedButtonStyle, { fontFamily: overrides.link_text_font }, textStyleOptions);
+        menu.defaultButtonStyle = applyAiStyle(menu.defaultButtonStyle, { fontFamily: overrides.link_text_font }, textStyleOptions, { startingRole: 'button' });
+        // The selected style mirrors the default's RESULTING sparse typography rather than being
+        // independently reconnected: it carries no role of its own (no maker path
+        // sets one, no migration adds one), so reconnecting it on its own path could resolve a
+        // different override shape than its sibling for the same ask. `global-role-propagation.ts`
+        // mirrors a later site-wide change onto it the same way (the default/selected sibling drop).
+        menu.selectedButtonStyle = {
+            ...omitTypography(menu.selectedButtonStyle ?? {}),
+            ...pickTypography(menu.defaultButtonStyle),
+        };
     }
     if (overrides.link_bg_color !== undefined && header.navigation) {
         header.navigation.defaultButtonStyle = {

package/lib/src/metadata-builder/builders/section-builders/about-section-builder.js

@@ -1,5 +1,5 @@
 import { isTiptapDocument, } from '../../parsers/section-tool-arguments';
-import { applyScalarFields, applyStyleFields, resolveGlobalPresetIntoStyle, } from '../section-field-utils';
+import { applyScalarFields, applyStyleFields, applyAiStyle, } from '../section-field-utils';
 import { applyColorThemeToReplacements, resolveShapeColorReplacementsAsync, } from '../shape-color-utils';
 import { BaseSectionBuilder } from './base-section-builder';
 import { validateAboutSection } from '../section-rules/about-section.rules';
@@ -24,7 +24,7 @@ export class AboutSectionBuilder extends BaseSectionBuilder {
         if (aboutArgs.title !== undefined) {
             if (isTiptapDocument(aboutArgs.title)) {
                 resolved.content.title = aboutArgs.title;
-                resolved.content.titleStyle = resolveGlobalPresetIntoStyle(resolved.content.titleStyle, textStyleOptions);
+                resolved.content.titleStyle = applyAiStyle(resolved.content.titleStyle, {}, textStyleOptions);
             }
             else {
                 resolved.content.title = aboutArgs.title;
@@ -33,7 +33,7 @@ export class AboutSectionBuilder extends BaseSectionBuilder {
         if (aboutArgs.paragraph !== undefined) {
             if (isTiptapDocument(aboutArgs.paragraph)) {
                 resolved.content.paragraph = aboutArgs.paragraph;
-                resolved.content.paragraphStyle = resolveGlobalPresetIntoStyle(resolved.content.paragraphStyle, textStyleOptions);
+                resolved.content.paragraphStyle = applyAiStyle(resolved.content.paragraphStyle, {}, textStyleOptions);
             }
             else {
                 resolved.content.paragraph = aboutArgs.paragraph;