@designcrowd/library.brand-page 6.2.11 → 6.2.12

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

@@ -1,5 +1,5 @@
 import { isTiptapDocument, } from '../../parsers/section-tool-arguments';
-import { applyButtonLink, applyScalarFields, applyStyleFields, resolveGlobalPresetIntoStyle, } from '../section-field-utils';
+import { applyButtonLink, applyScalarFields, applyStyleFields, applyAiStyle, } from '../section-field-utils';
 import { applyColorThemeToReplacements, resolveShapeColorReplacementsAsync, } from '../shape-color-utils';
 import { BaseSectionBuilder } from './base-section-builder';
 import { validateBannerSection } from '../section-rules/banner-section.rules';
@@ -44,7 +44,7 @@ export class BannerSectionBuilder extends BaseSectionBuilder {
         if (bannerArgs.title !== undefined) {
             if (isTiptapDocument(bannerArgs.title)) {
                 resolved.content.title = bannerArgs.title;
-                resolved.content.titleStyle = resolveGlobalPresetIntoStyle(resolved.content.titleStyle, textStyleOptions);
+                resolved.content.titleStyle = applyAiStyle(resolved.content.titleStyle, {}, textStyleOptions);
             }
             else {
                 resolved.content.title = bannerArgs.title;
@@ -53,7 +53,7 @@ export class BannerSectionBuilder extends BaseSectionBuilder {
         if (bannerArgs.description !== undefined) {
             if (isTiptapDocument(bannerArgs.description)) {
                 resolved.content.description = bannerArgs.description;
-                resolved.content.descriptionStyle = resolveGlobalPresetIntoStyle(resolved.content.descriptionStyle, textStyleOptions);
+                resolved.content.descriptionStyle = applyAiStyle(resolved.content.descriptionStyle, {}, textStyleOptions);
             }
             else {
                 resolved.content.description = bannerArgs.description;

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

@@ -1,5 +1,5 @@
 import { isTiptapDocument, } from '../../parsers/section-tool-arguments';
-import { applyButtonLink, applyScalarFields, applyStyleFields, resolveGlobalPresetIntoStyle, } from '../section-field-utils';
+import { applyButtonLink, applyScalarFields, applyStyleFields, applyAiStyle, } from '../section-field-utils';
 import { BaseSectionBuilder } from './base-section-builder';
 import { validateBookingSection } from '../section-rules/booking-section.rules';
 export class BookingSectionBuilder extends BaseSectionBuilder {
@@ -23,7 +23,7 @@ export class BookingSectionBuilder extends BaseSectionBuilder {
         if (bookingArgs.title !== undefined) {
             if (isTiptapDocument(bookingArgs.title)) {
                 resolved.content.title = bookingArgs.title;
-                resolved.content.titleStyle = resolveGlobalPresetIntoStyle(resolved.content.titleStyle, textStyleOptions);
+                resolved.content.titleStyle = applyAiStyle(resolved.content.titleStyle, {}, textStyleOptions);
             }
             else {
                 resolved.content.title = bookingArgs.title;
@@ -32,7 +32,7 @@ export class BookingSectionBuilder extends BaseSectionBuilder {
         if (bookingArgs.description !== undefined) {
             if (isTiptapDocument(bookingArgs.description)) {
                 resolved.content.description = bookingArgs.description;
-                resolved.content.descriptionStyle = resolveGlobalPresetIntoStyle(resolved.content.descriptionStyle, textStyleOptions);
+                resolved.content.descriptionStyle = applyAiStyle(resolved.content.descriptionStyle, {}, textStyleOptions);
             }
             else {
                 resolved.content.description = bookingArgs.description;

package/lib/src/metadata-builder/builders/section-builders/contact-form-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 { BaseSectionBuilder } from './base-section-builder';
 import { validateContactForm } from '../section-rules/contact-form.rules';
 export class ContactFormBuilder extends BaseSectionBuilder {
@@ -23,7 +23,7 @@ export class ContactFormBuilder extends BaseSectionBuilder {
         if (args.title !== undefined) {
             if (isTiptapDocument(args.title)) {
                 content.title = args.title;
-                content.titleStyle = resolveGlobalPresetIntoStyle(content.titleStyle, textStyleOptions);
+                content.titleStyle = applyAiStyle(content.titleStyle, {}, textStyleOptions);
             }
             else {
                 content.title = args.title;
@@ -32,7 +32,7 @@ export class ContactFormBuilder extends BaseSectionBuilder {
         if (args.description !== undefined) {
             if (isTiptapDocument(args.description)) {
                 content.description = args.description;
-                content.descriptionStyle = resolveGlobalPresetIntoStyle(content.descriptionStyle, textStyleOptions);
+                content.descriptionStyle = applyAiStyle(content.descriptionStyle, {}, textStyleOptions);
             }
             else {
                 content.description = args.description;
@@ -41,7 +41,7 @@ export class ContactFormBuilder extends BaseSectionBuilder {
         if (args.success_message !== undefined) {
             if (isTiptapDocument(args.success_message)) {
                 content.successMessage = args.success_message;
-                content.successMessageStyle = resolveGlobalPresetIntoStyle(content.successMessageStyle, textStyleOptions);
+                content.successMessageStyle = applyAiStyle(content.successMessageStyle, {}, textStyleOptions);
             }
             else {
                 content.successMessage = args.success_message;

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

@@ -1,5 +1,5 @@
 import { isTiptapDocument, } from '../../parsers/section-tool-arguments';
-import { applyScalarFields, applyStyleFields, isValidUrl, resolveGlobalPresetIntoStyle, } from '../section-field-utils';
+import { applyScalarFields, applyStyleFields, isValidUrl, applyAiStyle, } from '../section-field-utils';
 import { BaseSectionBuilder } from './base-section-builder';
 import { validateImagesSection } from '../section-rules/images-section.rules';
 import { ensureItemIds, generateItemId, removeItemsByIds, repositionItemByAnchor, } from '../item-id-utils';
@@ -96,7 +96,7 @@ export class ImagesSectionBuilder extends BaseSectionBuilder {
         if (args.title !== undefined) {
             if (isTiptapDocument(args.title)) {
                 content.title = args.title;
-                content.titleStyle = resolveGlobalPresetIntoStyle(content.titleStyle, textStyleOptions);
+                content.titleStyle = applyAiStyle(content.titleStyle, {}, textStyleOptions);
             }
             else {
                 content.title = args.title;
@@ -105,7 +105,7 @@ export class ImagesSectionBuilder extends BaseSectionBuilder {
         if (args.description !== undefined) {
             if (isTiptapDocument(args.description)) {
                 content.description = args.description;
-                content.descriptionStyle = resolveGlobalPresetIntoStyle(content.descriptionStyle, textStyleOptions);
+                content.descriptionStyle = applyAiStyle(content.descriptionStyle, {}, textStyleOptions);
             }
             else {
                 content.description = args.description;

package/lib/src/metadata-builder/builders/section-builders/mailing-list-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 { BaseSectionBuilder } from './base-section-builder';
 import { validateMailingList } from '../section-rules/mailing-list.rules';
 export class MailingListBuilder extends BaseSectionBuilder {
@@ -23,7 +23,7 @@ export class MailingListBuilder extends BaseSectionBuilder {
         if (mailingListArgs.title !== undefined) {
             if (isTiptapDocument(mailingListArgs.title)) {
                 content.title = mailingListArgs.title;
-                content.titleStyle = resolveGlobalPresetIntoStyle(content.titleStyle, textStyleOptions);
+                content.titleStyle = applyAiStyle(content.titleStyle, {}, textStyleOptions);
             }
             else {
                 content.title = mailingListArgs.title;

package/lib/src/metadata-builder/builders/section-builders/mailing-list-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 { BaseSectionBuilder } from './base-section-builder';
 import { validateMailingList } from '../section-rules/mailing-list.rules';
 export class MailingListSectionBuilder extends BaseSectionBuilder {
@@ -22,7 +22,7 @@ export class MailingListSectionBuilder extends BaseSectionBuilder {
         if (mailingListArgs.title !== undefined) {
             if (isTiptapDocument(mailingListArgs.title)) {
                 resolved.content.title = mailingListArgs.title;
-                resolved.content.titleStyle = resolveGlobalPresetIntoStyle(resolved.content.titleStyle, textStyleOptions);
+                resolved.content.titleStyle = applyAiStyle(resolved.content.titleStyle, {}, textStyleOptions);
             }
             else {
                 resolved.content.title = mailingListArgs.title;

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

@@ -1,5 +1,5 @@
 import { isTiptapDocument, } from '../../parsers/section-tool-arguments';
-import { applyScalarFields, resolveGlobalPresetIntoStyle, } from '../section-field-utils';
+import { applyScalarFields, applyAiStyle } from '../section-field-utils';
 import { BaseSectionBuilder } from './base-section-builder';
 import { validateProfile } from '../section-rules/profile.rules';
 export class ProfileSectionBuilder extends BaseSectionBuilder {
@@ -21,7 +21,7 @@ export class ProfileSectionBuilder extends BaseSectionBuilder {
         if (profileArgs.name !== undefined) {
             if (isTiptapDocument(profileArgs.name)) {
                 resolved.content.name = profileArgs.name;
-                resolved.content.nameStyle = resolveGlobalPresetIntoStyle(resolved.content.nameStyle, textStyleOptions);
+                resolved.content.nameStyle = applyAiStyle(resolved.content.nameStyle, {}, textStyleOptions);
             }
             else {
                 resolved.content.name = profileArgs.name;
@@ -30,7 +30,7 @@ export class ProfileSectionBuilder extends BaseSectionBuilder {
         if (profileArgs.title !== undefined) {
             if (isTiptapDocument(profileArgs.title)) {
                 resolved.content.title = profileArgs.title;
-                resolved.content.titleStyle = resolveGlobalPresetIntoStyle(resolved.content.titleStyle, textStyleOptions);
+                resolved.content.titleStyle = applyAiStyle(resolved.content.titleStyle, {}, textStyleOptions);
             }
             else {
                 resolved.content.title = profileArgs.title;
@@ -39,7 +39,7 @@ export class ProfileSectionBuilder extends BaseSectionBuilder {
         if (profileArgs.description !== undefined) {
             if (isTiptapDocument(profileArgs.description)) {
                 resolved.content.description = profileArgs.description;
-                resolved.content.descriptionStyle = resolveGlobalPresetIntoStyle(resolved.content.descriptionStyle, textStyleOptions);
+                resolved.content.descriptionStyle = applyAiStyle(resolved.content.descriptionStyle, {}, textStyleOptions);
             }
             else {
                 resolved.content.description = profileArgs.description;

package/lib/src/metadata-builder/builders/section-builders/shapes-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 { validateShapesSection } from '../section-rules/shapes-section.rules';
@@ -117,7 +117,7 @@ export class ShapesSectionBuilder extends BaseSectionBuilder {
         if (args.title !== undefined) {
             if (isTiptapDocument(args.title)) {
                 content.title = args.title;
-                content.titleStyle = resolveGlobalPresetIntoStyle(content.titleStyle, textStyleOptions);
+                content.titleStyle = applyAiStyle(content.titleStyle, {}, textStyleOptions);
             }
             else {
                 content.title = args.title;
@@ -126,7 +126,7 @@ export class ShapesSectionBuilder extends BaseSectionBuilder {
         if (args.description !== undefined) {
             if (isTiptapDocument(args.description)) {
                 content.description = args.description;
-                content.descriptionStyle = resolveGlobalPresetIntoStyle(content.descriptionStyle, textStyleOptions);
+                content.descriptionStyle = applyAiStyle(content.descriptionStyle, {}, textStyleOptions);
             }
             else {
                 content.description = args.description;

package/lib/src/metadata-builder/builders/section-builders/social-links-builder.js

@@ -1,4 +1,5 @@
-import { applyScalarFields, applyStyleFields } from '../section-field-utils';
+import { isTiptapDocument, } from '../../parsers/section-tool-arguments';
+import { applyAiStyle, applyScalarFields, applyStyleFields, } from '../section-field-utils';
 import { BaseSectionBuilder } from './base-section-builder';
 import { validateSocialLinks } from '../section-rules/social-links.rules';
 import { ensureItemIds, generateItemId, removeItemsByIds, repositionItemByAnchor, } from '../item-id-utils';
@@ -73,9 +74,14 @@ export class SocialLinksBuilder extends BaseSectionBuilder {
         if ('error' in resolved)
             return resolved.error;
         const content = resolved.content;
+        const textStyleOptions = this.getGlobalTextStyles(model);
         applyScalarFields(content, this.args, this.sectionType);
-        applyStyleFields(content, this.args, this.sectionType, this.getGlobalTextStyles(model));
+        applyStyleFields(content, this.args, this.sectionType, textStyleOptions);
         const args = this.args;
+        if (isTiptapDocument(args.title)) {
+            content.title = args.title;
+            content.titleStyle = applyAiStyle(content.titleStyle, {}, textStyleOptions);
+        }
         if (args._replace_items && args.links && Array.isArray(args.links)) {
             // Full replacement: discard existing links and rebuild from the payload.
             applySocialLinks(content, args.links);

package/lib/src/metadata-builder/builders/section-builders/testimonial-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 { validateTestimonialSection, TESTIMONIAL_ITEM_CAP, } from '../section-rules/testimonial-section.rules';
@@ -103,7 +103,7 @@ export class TestimonialSectionBuilder extends BaseSectionBuilder {
         if (args.title !== undefined) {
             if (isTiptapDocument(args.title)) {
                 content.title = args.title;
-                content.titleStyle = resolveGlobalPresetIntoStyle(content.titleStyle, textStyleOptions);
+                content.titleStyle = applyAiStyle(content.titleStyle, {}, textStyleOptions);
             }
             else {
                 content.title = args.title;

package/lib/src/metadata-builder/builders/section-builders/text-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, applyStoredDocStyleConsequences, normalizeStyleValue, } from '../section-field-utils';
 import { BaseSectionBuilder } from './base-section-builder';
 import { validateTextSection } from '../section-rules/text-section.rules';
 import { ensureItemIds, generateItemId, removeItemsByIds, repositionItemByAnchor, } from '../item-id-utils';
@@ -14,16 +14,18 @@ const resolveText = (value) => {
         return { value, wasTiptap: true };
     return { value: typeof value === 'string' ? value : '', wasTiptap: false };
 };
-const clearTextStyleTypeIfTiptap = (style, wasTiptap, textStyleOptions) => wasTiptap
-    ? resolveGlobalPresetIntoStyle(style, textStyleOptions)
-    : style;
 const createTextItem = (item, baseStyle, textStyleOptions) => {
-    const textStyle = (item.text_style ? { ...baseStyle, ...item.text_style } : { ...baseStyle });
     const { value, wasTiptap } = resolveText(item.text);
+    const incoming = normalizeIncomingStyle((item.text_style ?? {}));
+    // RTE text: role-aware apply (keep a named role + sparse override, else resolve-and-detach).
+    // Plain text: the section-level style still drives it, so a straight merge.
+    const textStyle = wasTiptap
+        ? applyAiStyle(baseStyle, incoming, textStyleOptions)
+        : { ...baseStyle, ...incoming };
     return {
         id: item.item_id || generateItemId(),
         text: value,
-        textStyle: clearTextStyleTypeIfTiptap(textStyle, wasTiptap, textStyleOptions),
+        textStyle,
     };
 };
 /**
@@ -33,6 +35,36 @@ const createTextItem = (item, baseStyle, textStyleOptions) => {
 const applyTextItems = (content, items, textStyleOptions) => {
     content.textItems = items.map((item) => createTextItem(item, content.textStyle || {}, textStyleOptions));
 };
+/**
+ * Run every item-level style value through `normalizeStyleValue` (letterSpacing 0-100 → em string,
+ * lineHeight → a plain numeric string, null → clear), same as the section-level `applyStyleFields`
+ * path does. Items are a separate hand-rolled path with three AI-facing entry points
+ * (`createTextItem`, the text+style update branch, the style-only patch); without this, a raw
+ * `item.text_style` merge would store e.g. `letterSpacing: 10` as the bare number 10.
+ */
+const normalizeIncomingStyle = (style) => {
+    const normalized = {};
+    for (const [k, v] of Object.entries(style)) {
+        const value = normalizeStyleValue(k, v);
+        if (value !== undefined)
+            normalized[k] = value;
+    }
+    return normalized;
+};
+/**
+ * A style-only patch (no new text in this call) on one stored item: role-aware apply (R19's
+ * reset-on-switch), then the same stored-doc consequences a section-level style field gets (R18's
+ * recolour, R19's relink) — items are a separate hand-rolled path, so they need the same field
+ * helper as `applyStyleFields`. Shared by the id-based merge and the single-field shorthand, so
+ * neither raw-merges `text_style` into item 0 on its own.
+ */
+const applyItemStyleOnlyPatch = (item, textStyle, textStyleOptions) => {
+    const existingStyle = item.textStyle;
+    const existingRole = existingStyle?.textStyleType;
+    const incoming = normalizeIncomingStyle(textStyle);
+    item.textStyle = applyAiStyle(existingStyle, incoming, textStyleOptions);
+    item.text = applyStoredDocStyleConsequences(item.text, existingRole, item.textStyle, incoming, textStyleOptions);
+};
 /**
  * Id-based merge (BP-5603): mirrors the section-level id contract one level
  * deeper.
@@ -56,14 +88,17 @@ const mergeTextItems = (content, items, removeIds, textStyleOptions) => {
                 continue;
             if (item.text !== undefined) {
                 const { value, wasTiptap } = resolveText(item.text);
+                const incoming = normalizeIncomingStyle((item.text_style ?? {}));
                 existing.text = value;
-                existing.textStyle = clearTextStyleTypeIfTiptap(existing.textStyle || {}, wasTiptap, textStyleOptions);
+                existing.textStyle = wasTiptap
+                    ? applyAiStyle(existing.textStyle || {}, incoming, textStyleOptions)
+                    : {
+                        ...(existing.textStyle || {}),
+                        ...incoming,
+                    };
             }
-            if (item.text_style && typeof item.text_style === 'object') {
-                existing.textStyle = {
-                    ...(existing.textStyle || {}),
-                    ...item.text_style,
-                };
+            else if (item.text_style && typeof item.text_style === 'object') {
+                applyItemStyleOnlyPatch(existing, item.text_style, textStyleOptions);
             }
             repositionItemByAnchor(content.textItems, existing, item.move_before_item_id);
         }
@@ -79,37 +114,33 @@ const mergeTextItems = (content, items, removeIds, textStyleOptions) => {
  * or shorthand for the first item).
  */
 const applySingleTextField = (content, args, textStyleOptions) => {
+    const incoming = normalizeIncomingStyle((args.text_style ?? {}));
     if (args.text !== undefined) {
         const { value, wasTiptap } = resolveText(args.text);
-        if (Array.isArray(content.textItems) && content.textItems.length > 0) {
+        const hasItem = Array.isArray(content.textItems) && content.textItems.length > 0;
+        const base = hasItem
+            ? content.textItems[0].textStyle || {}
+            : { ...(content.textStyle || {}) };
+        const textStyle = wasTiptap
+            ? applyAiStyle(base, incoming, textStyleOptions)
+            : { ...base, ...incoming };
+        if (hasItem) {
             content.textItems[0] = {
                 ...content.textItems[0],
                 text: value,
-                textStyle: clearTextStyleTypeIfTiptap(content.textItems[0].textStyle || {}, wasTiptap, textStyleOptions),
+                textStyle,
             };
         }
         else {
-            content.textItems = [
-                {
-                    id: generateItemId(),
-                    text: value,
-                    textStyle: clearTextStyleTypeIfTiptap({ ...(content.textStyle || {}) }, wasTiptap, textStyleOptions),
-                },
-            ];
+            content.textItems = [{ id: generateItemId(), text: value, textStyle }];
         }
+        return;
     }
     if (args.text_style &&
         typeof args.text_style === 'object' &&
         Array.isArray(content.textItems) &&
         content.textItems.length > 0) {
-        const mergedStyle = {
-            ...(content.textItems[0].textStyle || {}),
-            ...args.text_style,
-        };
-        content.textItems[0] = {
-            ...content.textItems[0],
-            textStyle: mergedStyle,
-        };
+        applyItemStyleOnlyPatch(content.textItems[0], args.text_style, textStyleOptions);
     }
 };
 export class TextSectionBuilder extends BaseSectionBuilder {

package/lib/src/metadata-builder/builders/section-field-maps.js

@@ -223,6 +223,7 @@ const supportMeStyleFields = defineFieldMap({
     button_text_style: 'buttonTextStyle',
 });
 const socialLinksStyleFields = defineFieldMap({
+    title_style: 'titleStyle',
     icon_fill_style: 'iconFillStyles',
     icon_background_style: 'iconBackgroundStyles',
 });

package/lib/src/metadata-builder/builders/section-field-utils.d.ts

@@ -1,6 +1,7 @@
 import type { Content } from '../../brand-page/models';
 import type { ButtonLinkType } from '../../brand-page/models';
 import type { TextStyleOptions } from '../../brand-page/models/styles.model';
+import { type ReconnectSpec } from '../../brand-page/utils/text-role-reconnect.util';
 import { type SectionToolArguments } from '../parsers/section-tool-arguments';
 export declare const isValidUrl: (value: unknown) => boolean;
 interface ButtonLinkContent {
@@ -24,35 +25,63 @@ export declare const applyScalarFields: (content: Content, args: SectionToolArgu
 /**
  * Convert AI-sent style value to the format expected by the model.
  * - letterSpacing: unitless 0-100 → em string (e.g., 50 → '0.5em')
+ * - lineHeight: coerced to a plain numeric string, UNSNAPPED — snapping here would shift a
+ *   value that's actually equal to its role (e.g. 1.25) off that equality before
+ *   `applyAiStyle` gets a chance to drop it as a role-equal non-override (R2). Only a value
+ *   that survives the role-equal check is snapped (`snapLineHeight`, in `applyAiStyle`), and the
+ *   drop runs AGAIN after snapping: a role can itself hold a non-grid value (e.g. heading3's
+ *   native 1.25), so comparing before snapping catches an exact match at full precision, and
+ *   re-comparing after catches a snap that LANDS the override exactly on the role's value.
  * - null → '' (explicitly clear/reset the property)
  * - everything else passes through as-is
  */
 export declare const normalizeStyleValue: (key: string, value: unknown) => unknown;
 /**
- * When an executor is about to mark a content-level text style "custom" by
- * clearing `textStyleType`, the resolved preset values (font, size, spacing,
- * etc.) must first be copied onto the style — otherwise the renderer falls
- * back to browser defaults because `textStyleType` no longer points at a
- * preset.
+ * Whether this call is a REAL canonical switch (R19): both the stored and the INCOMING role (the
+ * raw value the call sent, before any reconnect fallback) are canonical, and differ. Decided once
+ * from `incoming.textStyleType` and shared by `applyAiStyle` (which resets the style object) and
+ * the caller of `applyStoredDocStyleConsequences` (which resets the stored doc), so both agree: a
+ * retired-key call reconnects in `applyAiStyle` (not a switch — it keeps the look as overrides) but
+ * can still land on a canonical role that differs from the stored one, which deriving it from the
+ * RESULT instead would misread as a switch and relink a doc whose overrides were meant to survive.
+ */
+export declare const isRealCanonicalSwitch: (existingRole: unknown, incomingRole: unknown) => boolean;
+/**
+ * Apply an AI-sent style to a field, honouring the role model under partial-update semantics
+ * (a property present = update; absent = no change).
+ *
+ * The role is the EFFECTIVE one — `incoming.textStyleType ?? existing.textStyleType` — so a sparse
+ * update that omits the role KEEPS the element's current role. When that role is canonical, keep
+ * the link and store a sparse override: incoming props layer on and `normalizeTextStyleAgainstRole`
+ * drops any prop equal to the role, so the page-scoped role CSS drives it and a later global edit
+ * repaints the block.
+ *
+ * A REAL canonical switch (both the old and the new role are canonical, and differ — R19) is a
+ * reset, not a patch: it starts from `omitTypography(existing)` before layering this call's own
+ * style on top, so a stale override from the old role doesn't survive as a bogus override of the
+ * new one. Colour, background, alignment and `applyAutoScale` aren't typography, so they carry
+ * over untouched; the call's own text and overrides win (they're applied after the reset).
  *
- * The category is read from the existing `style.textStyleType`, which is the
- * authoritative per-section + per-field reference set by the content factory.
- * Existing style values win over preset defaults (the content may already
- * carry user overrides on top of the preset).
+ * Any other role — a retired key the pipeline still emits, `none`, or no role at all — reconnects
+ * the way the upgrade does (`reconnectTextStyle`, with the field's `spec`): its starting role, else
+ * the retired role's successor, else the role nearest its size, keeping its look as overrides.
  */
-export declare const resolveGlobalPresetIntoStyle: (style: object | undefined, textStyleOptions: TextStyleOptions | undefined) => Record<string, unknown>;
+export declare const applyAiStyle: <T extends object>(existing: T | undefined, incoming: Record<string, unknown>, textStyleOptions: TextStyleOptions | undefined, spec?: ReconnectSpec) => T;
 /**
- * Applies per-element style overrides while detaching the element from any
- * global text-style preset. When a style is bound to a `textStyleType` preset,
- * the renderer (`getCopyrightTextStyle` / `getTextStyleByContentTextStyle`)
- * replaces the whole style with that preset and discards per-element values such
- * as `fontFamily`. Resolving the preset in and clearing `textStyleType` makes the
- * override stick — the same disconnect rule section content follows.
+ * BP-5969 (R18, R19) — what a style-only patch (no new text in the same call) does to an already-
+ * stored RTE doc. A real role switch relinks every run to the new role (the document-level half of
+ * the reset `applyAiStyle` already gave the style object above), keeping any typography the call's
+ * own `nextStyle` still overrides via `relinkDocToRole`'s `styleOverrides` arg. A colour-only patch,
+ * OR a colour riding along with a switch in the same call (James Joung, 2026-10-01: a role switch
+ * and a recolour with no text both apply), recolours every run and clears the now-redundant style
+ * colour (kept only when the doc has no run to hold it — an empty field's colour waits for the
+ * maker's first keystroke, `buildInitialMarks`). Both consequences can apply to one call: the
+ * switch's relink runs first, then the colour branch recolours the relinked doc.
  *
- * Idempotent: once `textStyleType` is cleared, subsequent calls just merge the
- * updates without re-resolving a preset.
+ * No-op for anything but a stored Tiptap document — a legacy HTML string is handled by the caller's
+ * own `ApplyColorToRTE` rewrite instead.
  */
-export declare const applyDetachedStyleOverride: <T extends object>(current: T | undefined, updates: Partial<T>, textStyleOptions: TextStyleOptions | undefined) => T;
+export declare const applyStoredDocStyleConsequences: (existingText: unknown, existingRole: unknown, nextStyle: Record<string, unknown>, incomingStyle: Record<string, unknown>, textStyleOptions: TextStyleOptions | undefined) => unknown;
 /**
  * Rewrites the stored RTE HTML's inline colour marks. Injectable for tests;
  * the default uses the external Tiptap editor (font-propagation precedent).