@designcrowd/library.brand-page 6.2.11 → 6.2.12

package/src/metadata-builder/builders/global-styles-builder.test.ts

@@ -3,6 +3,10 @@ import type { BrandPageModel } from '../../brand-page/models';
 import type { UpdateGlobalStylesArguments } from '../parsers/ai-toolcall-parser';
 import { BUILDER_TYPES } from '../models';
 import { GlobalStylesBuilder } from './global-styles-builder';
+import {
+  roleTypographyStyle,
+  runTypographyFillValue,
+} from '../../brand-page/utils/text-role-css.util';
 
 /**
  * BP-6082: for a button shape change the AI's update_global_styles carries only
@@ -105,3 +109,1019 @@ describe('GlobalStylesBuilder — button preset shape (BP-6082)', () => {
     );
   });
 });
+
+// BP-5969 O2/T3.8 — a role is guaranteed to have a value (James Joung, "roles will now be
+// guaranteed to have value"): the AI global-styles merge must never blank one. The pipeline's
+// client turns a cleared field into `null` or `''`; either must be skipped, not written.
+describe('GlobalStylesBuilder — never empties a role value (T3.8)', () => {
+  it('never empties a role value', async () => {
+    const model = {
+      styles: {
+        textStyles: {
+          textStyleOptions: {
+            heading2: {
+              style: {
+                fontSize: '2.25em',
+                lineHeight: '1.3',
+                fontFamily: 'Lato',
+              },
+              isModified: false,
+            },
+          },
+        },
+      },
+    } as unknown as BrandPageModel;
+
+    const { model: result } = await run(
+      {
+        textStyles: {
+          textStyleOptions: {
+            heading2: {
+              style: {
+                fontSize: '',
+                lineHeight: null as unknown as string,
+                fontFamily: 'Poppins',
+              },
+            },
+          },
+        },
+      },
+      model,
+    );
+    const ts = result.styles.textStyles.textStyleOptions as Record<
+      string,
+      { style: { fontSize?: string; lineHeight?: string; fontFamily?: string } }
+    >;
+
+    expect(ts.heading2.style.fontSize).toBe('2.25em');
+    expect(ts.heading2.style.lineHeight).toBe('1.3');
+    expect(ts.heading2.style.fontFamily).toBe('Poppins');
+  });
+});
+
+// BP-5969 (N1, re-review fix pass) — fontStyle/fontWeight/textDecoration/letterSpacing have a
+// CSS-neutral default the role class always emits, so a cleared field for one of THESE is a
+// genuine "turn it off": the property is written to that neutral, not deleted. Deleting it left
+// the role object without the key, so `roleTypographyStyle` (which only refs a property the role
+// object actually holds) emitted nothing for plain text — falling through to inherit whatever
+// ancestor happened to set (`tw-font-semibold` on RequestPayment/shop text) — while a rich-text
+// run still refs the class's neutral regardless, so plain and rich painted differently after an
+// AI reset.
+describe('GlobalStylesBuilder — a cleared neutral-backed property resets, not skips', () => {
+  it('a null fontStyle and an empty textDecoration clear to the role default, not the old value', async () => {
+    const model = {
+      styles: {
+        textStyles: {
+          textStyleOptions: {
+            heading2: {
+              style: {
+                fontSize: '2.25em',
+                fontStyle: 'italic',
+                textDecoration: 'underline',
+              },
+              isModified: false,
+            },
+          },
+        },
+      },
+    } as unknown as BrandPageModel;
+
+    const { model: result } = await run(
+      {
+        textStyles: {
+          textStyleOptions: {
+            heading2: {
+              style: {
+                fontStyle: null as unknown as string,
+                textDecoration: '',
+              },
+            },
+          },
+        },
+      },
+      model,
+    );
+    const ts = result.styles.textStyles.textStyleOptions as Record<
+      string,
+      {
+        style: {
+          fontSize?: string;
+          fontStyle?: string;
+          textDecoration?: string;
+        };
+      }
+    >;
+
+    expect(ts.heading2.style.fontStyle).toBe('normal');
+    expect(ts.heading2.style.textDecoration).toBe('none');
+    expect(ts.heading2.style.fontSize).toBe('2.25em');
+  });
+
+  it('an AI null reset leaves the role holding the neutral, so plain and rich text still agree', async () => {
+    const model = {
+      styles: {
+        textStyles: {
+          textStyleOptions: {
+            heading2: {
+              style: { fontSize: '2.25em', fontWeight: 'bold' },
+              isModified: false,
+            },
+          },
+        },
+      },
+    } as unknown as BrandPageModel;
+
+    const { model: result } = await run(
+      {
+        textStyles: {
+          textStyleOptions: {
+            heading2: { style: { fontWeight: null as unknown as string } },
+          },
+        },
+      },
+      model,
+    );
+    const ts = result.styles.textStyles.textStyleOptions as Record<
+      string,
+      { style: { fontSize?: string; fontWeight?: string } }
+    >;
+    const roleStyle = ts.heading2.style;
+
+    expect(Object.prototype.hasOwnProperty.call(roleStyle, 'fontWeight')).toBe(
+      true,
+    );
+    expect(roleStyle.fontWeight).toBe('normal');
+
+    // With the key held (not deleted), a plain-text painter sees the role define the property
+    // and references its var — the same reference a rich-text run always emits for a
+    // neutral-backed attr. Both resolve through the same class-level `--role-font-weight`, so
+    // an ancestor's own font-weight (e.g. a bold wrapper) can no longer leak through on one side
+    // only.
+    expect(roleTypographyStyle({}, roleStyle).fontWeight).toBe(
+      'var(--role-font-weight)',
+    );
+    expect(runTypographyFillValue('fontWeight', roleStyle, undefined)).toBe(
+      'var(--role-font-weight)',
+    );
+  });
+
+  it('accepts a stored normal letter spacing and still applies other global styles', async () => {
+    const model = {
+      styles: {
+        backgroundStyles: { style: { background: '#ffffff' } },
+        buttonStyles: {
+          style: {},
+          iconStyle: {},
+          selectedButtonStyleId: 'BUTTON_STYLE_4',
+        },
+        textStyles: {
+          textStyleOptions: {
+            heading2: {
+              style: { fontSize: '2.25em', letterSpacing: '0.1em' },
+              isModified: false,
+            },
+          },
+        },
+      },
+    } as unknown as BrandPageModel;
+
+    const cleared = await run(
+      {
+        textStyles: {
+          textStyleOptions: {
+            heading2: { style: { letterSpacing: null as unknown as string } },
+          },
+        },
+      },
+      model,
+    );
+    const { model: result, errors } = await run(
+      {
+        backgroundStyles: { backgroundColor: '#111111' },
+        buttonStyles: { style: { backgroundColor: '#222222' } },
+        textStyles: {
+          textStyleOptions: {
+            heading2: { style: { letterSpacing: 'normal' } },
+          },
+        },
+      },
+      cleared.model,
+    );
+
+    expect(errors).toBeUndefined();
+    expect(
+      result.styles.textStyles.textStyleOptions.heading2.style.letterSpacing,
+    ).toBe('normal');
+    expect(result.styles.backgroundStyles.style.background).toBe('#111111');
+    expect(result.styles.buttonStyles.style.backgroundColor).toBe('#222222');
+  });
+});
+
+// BP-5969 T6.1 — the baseline canonical-role merge (unchanged by Phase 6's retired-key rework):
+// a v22+ model's own canonical role merges directly, is marked modified, and every legacy slot
+// (still present, hidden) is left exactly as it was.
+describe('GlobalStylesBuilder — canonical role merge (T6.1)', () => {
+  it('a v22 model merges heading2.style.fontFamily onto heading2, marks it modified, legacy untouched', async () => {
+    const model = {
+      styles: {
+        textStyles: {
+          textStyleOptions: {
+            heading2: { style: { fontFamily: 'Lato' }, isModified: false },
+            headings: { style: { fontFamily: 'Lato' }, isModified: false },
+          },
+        },
+      },
+    } as unknown as BrandPageModel;
+
+    const { model: result } = await run(
+      {
+        textStyles: {
+          textStyleOptions: { heading2: { style: { fontFamily: 'Oswald' } } },
+        },
+      },
+      model,
+    );
+    const ts = result.styles.textStyles.textStyleOptions as Record<
+      string,
+      { style: { fontFamily?: string }; isModified: boolean }
+    >;
+
+    expect(ts.heading2.style.fontFamily).toBe('Oswald');
+    expect(ts.heading2.isModified).toBe(true);
+    expect(ts.headings.style.fontFamily).toBe('Lato');
+    expect(ts.headings.isModified).toBe(false);
+  });
+});
+
+// BP-5969 R17 — role definitions (textStyleOptions) stay literal-only: a var(...) ref there is
+// rejected, unlike the same attr on an RTE mark (section-args-validator's role-var exemption).
+describe('GlobalStylesBuilder — validateAsync (R17 role definitions stay literal)', () => {
+  const validate = (args: UpdateGlobalStylesArguments) =>
+    new GlobalStylesBuilder({
+      id: 'g1',
+      type: BUILDER_TYPES.UPDATE_GLOBAL_STYLES,
+      payload: args,
+    }).validateAsync();
+
+  it('errors when a role definition carries a var(--role-...) ref', async () => {
+    const { errors } = await validate({
+      textStyles: {
+        textStyleOptions: {
+          heading2: { style: { fontSize: 'var(--role-font-size)' } },
+        },
+      },
+    });
+
+    expect(errors).toHaveLength(1);
+    expect(errors[0]).toMatch(/fontSize/);
+  });
+
+  it('passes a literal role definition', async () => {
+    const { errors } = await validate({
+      textStyles: {
+        textStyleOptions: { heading2: { style: { fontSize: '2.5em' } } },
+      },
+    });
+
+    expect(errors).toHaveLength(0);
+  });
+
+  it('errors when keepRuns carries a non-string entry (R16)', async () => {
+    const { errors } = await validate({
+      textStyles: { keepRuns: ['Taste', 42 as unknown as string] },
+    });
+
+    expect(errors).toHaveLength(1);
+    expect(errors[0]).toMatch(/keepRuns/);
+  });
+
+  it('passes a valid keepRuns array', async () => {
+    const { errors } = await validate({
+      textStyles: { keepRuns: ['Taste'] },
+    });
+
+    expect(errors).toHaveLength(0);
+  });
+});
+
+// BP-5969 R7 — a retired global key maps onto its successor role(s), not a hidden option.
+describe('GlobalStylesBuilder — retired global key mapping (R7)', () => {
+  const HEADING_TIERS = [
+    'heading1',
+    'heading2',
+    'heading3',
+    'heading4',
+    'heading5',
+    'heading6',
+  ] as const;
+
+  const makeRoleModel = () => {
+    const textStyleOptions: Record<string, unknown> = {
+      titles: { style: { fontFamily: 'Lato', fontSize: '2.25em' } },
+      headings: { style: { fontFamily: 'Lato', fontSize: '1.5em' } },
+      paragraphs: { style: { fontFamily: 'Lato', fontSize: '1em' } },
+      buttons: { style: { fontFamily: 'Lato', fontSize: '1em' } },
+    };
+
+    for (const tier of HEADING_TIERS) {
+      textStyleOptions[tier] = { style: { fontFamily: 'Lato' } };
+    }
+
+    for (const tier of ['paragraph1', 'paragraph2', 'paragraph3', 'button']) {
+      textStyleOptions[tier] = { style: { fontFamily: 'Lato' } };
+    }
+
+    return {
+      styles: { textStyles: { textStyleOptions } },
+      pages: [],
+    } as unknown as BrandPageModel;
+  };
+
+  it('a retired "headings" family lands on heading2–heading6; the hidden slot is untouched', async () => {
+    const model = makeRoleModel();
+    const { model: result } = await run(
+      {
+        textStyles: {
+          textStyleOptions: { headings: { style: { fontFamily: 'Oswald' } } },
+        },
+      },
+      model,
+    );
+    const ts = result.styles.textStyles.textStyleOptions as Record<
+      string,
+      { style: { fontFamily?: string } }
+    >;
+
+    expect(ts.heading1.style.fontFamily).toBe('Lato');
+
+    for (const tier of [
+      'heading2',
+      'heading3',
+      'heading4',
+      'heading5',
+      'heading6',
+    ]) {
+      expect(ts[tier].style.fontFamily).toBe('Oswald');
+    }
+
+    // hidden legacy slot: never written
+    expect(ts.headings.style.fontFamily).toBe('Lato');
+  });
+
+  it('a retired "titles" size lands on only the computeLegacyTargets titles tier', async () => {
+    const model = makeRoleModel();
+    const { model: result } = await run(
+      {
+        textStyles: {
+          textStyleOptions: { titles: { style: { fontSize: '3em' } } },
+        },
+      },
+      model,
+    );
+    const ts = result.styles.textStyles.textStyleOptions as Record<
+      string,
+      { style: { fontSize?: string } }
+    >;
+    const touched = HEADING_TIERS.filter(
+      (tier) => ts[tier].style.fontSize === '3em',
+    );
+
+    expect(touched).toHaveLength(1);
+    // hidden legacy slot: never written (still its original size)
+    expect(ts.titles.style.fontSize).toBe('2.25em');
+  });
+
+  it('a retired "headings" fontSize lands on only the computeLegacyTargets headings tier, not every h2–h6 (T7.3)', async () => {
+    const model = makeRoleModel();
+    const { model: result } = await run(
+      {
+        textStyles: {
+          textStyleOptions: { headings: { style: { fontSize: '2em' } } },
+        },
+      },
+      model,
+    );
+    const ts = result.styles.textStyles.textStyleOptions as Record<
+      string,
+      { style: { fontSize?: string } }
+    >;
+    const touched = HEADING_TIERS.filter(
+      (tier) => ts[tier].style.fontSize === '2em',
+    );
+
+    expect(touched).toHaveLength(1);
+    expect(ts.headings.style.fontSize).toBe('1.5em');
+  });
+
+  it('a retired "paragraphs" fontSize lands on only its one tier; a family change still reaches every paragraph tier', async () => {
+    const model = makeRoleModel();
+    const { model: result } = await run(
+      {
+        textStyles: {
+          textStyleOptions: {
+            paragraphs: { style: { fontSize: '1.2em', fontFamily: 'Oswald' } },
+          },
+        },
+      },
+      model,
+    );
+    const ts = result.styles.textStyles.textStyleOptions as Record<
+      string,
+      { style: { fontSize?: string; fontFamily?: string } }
+    >;
+    const sizeTouched = (
+      ['paragraph1', 'paragraph2', 'paragraph3'] as const
+    ).filter((tier) => ts[tier].style.fontSize === '1.2em');
+
+    expect(sizeTouched).toHaveLength(1);
+
+    for (const tier of ['paragraph1', 'paragraph2', 'paragraph3'] as const) {
+      expect(ts[tier].style.fontFamily).toBe('Oswald');
+    }
+
+    expect(ts.paragraphs.style.fontSize).toBe('1em'); // hidden slot untouched
+  });
+});
+
+// BP-5969 R10 (ADR-0020) — a role is typography only; colour never persists onto a definition.
+describe('GlobalStylesBuilder — role definition stores no colour (R10)', () => {
+  it('a colour sent on a canonical role is dropped; its typography still merges', async () => {
+    const model = {
+      styles: {
+        textStyles: {
+          textStyleOptions: {
+            heading2: { style: { fontFamily: 'Lato' }, isModified: false },
+          },
+        },
+      },
+      pages: [],
+    } as unknown as BrandPageModel;
+
+    const {
+      model: result,
+      errors,
+      warnings,
+    } = await run(
+      {
+        textStyles: {
+          textStyleOptions: {
+            heading2: { style: { color: '#222222', fontFamily: 'Oswald' } },
+          },
+        },
+      },
+      model,
+    );
+    const heading2 = (
+      result.styles.textStyles.textStyleOptions as unknown as Record<
+        string,
+        { style: Record<string, unknown> }
+      >
+    ).heading2.style;
+
+    expect(errors ?? []).toEqual([]);
+    expect(warnings).toEqual([
+      'Ignored role color for heading2; apply colour to the affected sections instead.',
+    ]);
+    expect(heading2.color).toBeUndefined();
+    expect(heading2.fontFamily).toBe('Oswald');
+  });
+});
+
+// BP-5969 R21 — the global styles builder validates before it mutates anything (the GAP: buildAsync
+// never called its own validateAsync, so an invalid role value was stored unchecked).
+describe('GlobalStylesBuilder — buildAsync validates before mutating (R21)', () => {
+  it('an invalid role fontSize returns the error and leaves the model untouched; no propagation runs', async () => {
+    const model = {
+      styles: {
+        textStyles: {
+          textStyleOptions: {
+            heading2: { style: { fontFamily: 'Lato' }, isModified: false },
+          },
+        },
+      },
+      pages: [
+        {
+          id: 'p1',
+          contents: [
+            {
+              id: 'c1',
+              type: 'about-section',
+              title: 'x',
+              titleStyle: { textStyleType: 'heading2', fontFamily: 'Lato' },
+            },
+          ],
+        },
+      ],
+    } as unknown as BrandPageModel;
+    const before = JSON.stringify(model);
+
+    const { model: result, errors } = await run(
+      {
+        textStyles: {
+          textStyleOptions: { heading2: { style: { fontSize: '20em' } } },
+        },
+      },
+      model,
+    );
+
+    expect(errors).toBeDefined();
+    expect(errors!.length).toBeGreaterThan(0);
+    expect(JSON.stringify(result)).toBe(before);
+  });
+
+  // B5 — a role's fontWeight/fontStyle/textDecoration is written verbatim into a page-level SSR
+  // <style> block (text-role-css.util.ts roleDeclarations), so an unvalidated value is a
+  // stored-XSS sink. An attempted CSS-breakout value must be rejected like any other bad input.
+  it('rejects an unrecognized fontWeight/fontStyle/textDecoration value (B5)', async () => {
+    const model = {
+      styles: { textStyles: { textStyleOptions: {} } },
+      pages: [{ id: 'p1', contents: [] }],
+    } as unknown as BrandPageModel;
+    const before = JSON.stringify(model);
+
+    const { errors: weightErrors } = await run(
+      {
+        textStyles: {
+          textStyleOptions: {
+            heading2: {
+              style: { fontWeight: '700}</style><script>alert(1)</script>' },
+            },
+          },
+        },
+      },
+      model,
+    );
+
+    expect(weightErrors).toBeDefined();
+    expect(weightErrors!.length).toBeGreaterThan(0);
+
+    const { errors: styleErrors } = await run(
+      {
+        textStyles: {
+          textStyleOptions: {
+            heading2: { style: { fontStyle: 'normal; } body { display:none' } },
+          },
+        },
+      },
+      model,
+    );
+
+    expect(styleErrors).toBeDefined();
+    expect(styleErrors!.length).toBeGreaterThan(0);
+
+    const { errors: decorationErrors } = await run(
+      {
+        textStyles: {
+          textStyleOptions: {
+            heading2: { style: { textDecoration: 'none}</style>' } },
+          },
+        },
+      },
+      model,
+    );
+
+    expect(decorationErrors).toBeDefined();
+    expect(decorationErrors!.length).toBeGreaterThan(0);
+    expect(JSON.stringify(model)).toBe(before);
+  });
+
+  it('accepts a recognized fontWeight/fontStyle/textDecoration value', async () => {
+    const model = {
+      styles: { textStyles: { textStyleOptions: {} } },
+      pages: [{ id: 'p1', contents: [] }],
+    } as unknown as BrandPageModel;
+
+    const { errors } = await run(
+      {
+        textStyles: {
+          textStyleOptions: {
+            heading2: {
+              style: {
+                fontWeight: 'bold',
+                fontStyle: 'italic',
+                textDecoration: 'underline',
+              },
+            },
+          },
+        },
+      },
+      model,
+    );
+
+    expect(errors ?? []).toEqual([]);
+  });
+
+  // The maker's strike + underline toggles compose text-decoration (formatting.ts's
+  // decorationSet/composeDecoration), and the role-lift migration of a legacy <u><s> run does the
+  // same (rte-role-lift.util.ts) — so a role definition must accept the combined value, not just a
+  // single keyword (N1).
+  it('accepts a combined text-decoration value ("underline line-through") the product itself writes (N1)', async () => {
+    const model = {
+      styles: { textStyles: { textStyleOptions: {} } },
+      pages: [{ id: 'p1', contents: [] }],
+    } as unknown as BrandPageModel;
+
+    const { errors } = await run(
+      {
+        textStyles: {
+          textStyleOptions: {
+            heading2: { style: { textDecoration: 'underline line-through' } },
+          },
+        },
+      },
+      model,
+    );
+
+    expect(errors ?? []).toEqual([]);
+  });
+
+  // The pipeline may emit a bare JSON number for an enum-checked attr; a prior fix-pass regression
+  // made that throw inside the check's own `.trim()` call, hitting the section path's fail-OPEN
+  // bug (base-section-builder.ts) and the global path's opaque "failed unexpectedly" error (N3).
+  it('accepts a bare numeric fontWeight instead of throwing on .trim() (N3)', async () => {
+    const model = {
+      styles: { textStyles: { textStyleOptions: {} } },
+      pages: [{ id: 'p1', contents: [] }],
+    } as unknown as BrandPageModel;
+
+    const { errors } = await run(
+      {
+        textStyles: {
+          textStyleOptions: {
+            heading2: { style: { fontWeight: 700 as unknown as string } },
+          },
+        },
+      },
+      model,
+    );
+
+    expect(errors ?? []).toEqual([]);
+  });
+
+  it('canonicalises a bare numeric lineHeight the same as a non-canonical string spelling (N3)', async () => {
+    const model = {
+      styles: {
+        textStyles: {
+          textStyleOptions: {
+            heading2: { style: { fontFamily: 'Lato' }, isModified: false },
+          },
+        },
+      },
+      pages: [{ id: 'p1', contents: [] }],
+    } as unknown as BrandPageModel;
+
+    const { model: result, errors } = await run(
+      {
+        textStyles: {
+          textStyleOptions: {
+            heading2: { style: { lineHeight: 1 as unknown as string } },
+          },
+        },
+      },
+      model,
+    );
+
+    expect(errors ?? []).toEqual([]);
+    expect(
+      (
+        result.styles!.textStyles!.textStyleOptions as unknown as Record<
+          string,
+          { style: Record<string, unknown> }
+        >
+      ).heading2.style.lineHeight,
+    ).toBe('1');
+  });
+
+  // R3 — a stored number never strictly equals a block's string '700' (runTypographyFillValue's
+  // `!==` comparison), so a role fontWeight must be canonicalised to its string form too.
+  it('stores a bare numeric fontWeight as its string form (R3)', async () => {
+    const model = {
+      styles: {
+        textStyles: {
+          textStyleOptions: {
+            heading2: { style: { fontFamily: 'Lato' }, isModified: false },
+          },
+        },
+      },
+      pages: [{ id: 'p1', contents: [] }],
+    } as unknown as BrandPageModel;
+
+    const { model: result, errors } = await run(
+      {
+        textStyles: {
+          textStyleOptions: {
+            heading2: { style: { fontWeight: 700 as unknown as string } },
+          },
+        },
+      },
+      model,
+    );
+
+    expect(errors ?? []).toEqual([]);
+    expect(
+      (
+        result.styles!.textStyles!.textStyleOptions as unknown as Record<
+          string,
+          { style: Record<string, unknown> }
+        >
+      ).heading2.style.fontWeight,
+    ).toBe('700');
+  });
+
+  // S4 — the pipeline's own tool docs showed a "1.0" example; the validator's spelling check
+  // (shared with strict RTE mark validation, R17) would otherwise reject it and drop the whole
+  // call. The library canonicalises a role's lineHeight spelling before validating, in place, so
+  // the stored value ends up canonical too — not just this one check.
+  it('canonicalises a non-canonical lineHeight spelling before validating (S4)', async () => {
+    const model = {
+      styles: {
+        textStyles: {
+          textStyleOptions: {
+            heading2: { style: { fontFamily: 'Lato' }, isModified: false },
+          },
+        },
+      },
+      pages: [{ id: 'p1', contents: [] }],
+    } as unknown as BrandPageModel;
+
+    const { model: result, errors } = await run(
+      {
+        textStyles: {
+          textStyleOptions: { heading2: { style: { lineHeight: '1.0' } } },
+        },
+      },
+      model,
+    );
+
+    expect(errors ?? []).toEqual([]);
+    expect(
+      (
+        result.styles!.textStyles!.textStyleOptions as unknown as Record<
+          string,
+          { style: Record<string, unknown> }
+        >
+      ).heading2.style.lineHeight,
+    ).toBe('1');
+  });
+
+  it('does not mutate numeric or non-canonical role values during validation', async () => {
+    const payload = {
+      textStyles: {
+        textStyleOptions: {
+          heading2: {
+            style: {
+              lineHeight: '1.0',
+              fontWeight: 700 as unknown as string,
+            },
+          },
+        },
+      },
+    } as UpdateGlobalStylesArguments;
+    const builder = new GlobalStylesBuilder({
+      id: 'g1',
+      type: BUILDER_TYPES.UPDATE_GLOBAL_STYLES,
+      payload,
+    });
+
+    expect((await builder.validateAsync()).errors).toEqual([]);
+    expect(payload.textStyles!.textStyleOptions!.heading2!.style).toEqual({
+      lineHeight: '1.0',
+      fontWeight: 700,
+    });
+  });
+
+  // S3 — a throwing check used to be swallowed as "no errors" (every check skipped, not just the
+  // one that threw), so a value with an unexpected runtime shape sailed through unvalidated.
+  it('fails closed when a check throws instead of silently accepting the call (S3)', async () => {
+    const model = {
+      styles: { textStyles: { textStyleOptions: {} } },
+      pages: [{ id: 'p1', contents: [] }],
+    } as unknown as BrandPageModel;
+    const before = JSON.stringify(model);
+
+    // fontSize is typed as a string; a runtime number throws inside the check's .trim() call.
+    const { errors } = await run(
+      {
+        textStyles: {
+          textStyleOptions: {
+            heading2: { style: { fontSize: 20 as unknown as string } },
+          },
+        },
+      },
+      model,
+    );
+
+    expect(errors).toBeDefined();
+    expect(errors!.length).toBeGreaterThan(0);
+    expect(JSON.stringify(model)).toBe(before);
+  });
+});
+
+// The pipeline sends full role patches. Propagating an unchanged field would turn a colour-only
+// request into a site-wide restyle and erase intentional literal accents.
+describe('GlobalStylesBuilder — an unchanged resend keeps literal overrides', () => {
+  it('does not relink an existing Oswald literal when the role already has Oswald', async () => {
+    const model = {
+      styles: {
+        textStyles: {
+          textStyleOptions: {
+            heading2: { style: { fontFamily: 'Oswald' }, isModified: false },
+          },
+        },
+      },
+      pages: [
+        {
+          id: 'p1',
+          contents: [
+            {
+              id: 'c1',
+              type: 'about-section',
+              title: 'Fine Grooming',
+              titleStyle: { textStyleType: 'heading2', fontFamily: 'Oswald' },
+            },
+          ],
+        },
+      ],
+    } as unknown as BrandPageModel;
+
+    const { model: result, errors } = await run(
+      {
+        textStyles: {
+          textStyleOptions: { heading2: { style: { fontFamily: 'Oswald' } } },
+        },
+      },
+      model,
+    );
+
+    const titleStyle = (
+      result.pages[0].contents[0] as unknown as Record<
+        string,
+        Record<string, unknown>
+      >
+    ).titleStyle;
+
+    expect(errors ?? []).toEqual([]);
+    expect(titleStyle.fontFamily).toBe('Oswald');
+  });
+});
+
+// The pipeline sends weight, style and decoration only when the user asked, so each relinks the
+// role's existing content even when it equals the stored role.
+describe('GlobalStylesBuilder — emphasis reaches existing content (BP-5969)', () => {
+  const rteDoc = (runs: { text: string; marks?: unknown[] }[]) => ({
+    type: 'doc',
+    content: [
+      {
+        type: 'paragraph',
+        content: runs.map((r) => ({ type: 'text', ...r })),
+      },
+    ],
+  });
+
+  type Run = {
+    text: string;
+    marks?: { type: string; attrs?: Record<string, unknown> }[];
+  };
+
+  const runsOf = (doc: unknown): Run[] =>
+    (doc as { content: { content: Run[] }[] }).content[0].content;
+
+  const emptyModel = () =>
+    ({
+      styles: { textStyles: { textStyleOptions: {} } },
+      pages: [{ id: 'p1', contents: [] }],
+    }) as unknown as BrandPageModel;
+
+  it.each([
+    { fontWeight: 'bold', fontStyle: 'italic', textDecoration: 'underline' },
+    { fontWeight: 'normal', fontStyle: 'normal', textDecoration: 'none' },
+    { textDecoration: 'line-through' },
+    { textDecoration: 'underline line-through' },
+    { textDecoration: 'underline ' },
+    { textDecoration: 'underline line-through ' },
+  ])('accepts %o', async (style) => {
+    const { errors } = await run(
+      { textStyles: { textStyleOptions: { heading2: { style } } } },
+      emptyModel(),
+    );
+
+    expect(errors ?? []).toEqual([]);
+  });
+
+  it('heading2 fontStyle italic relinks a pinned literal and drops the italic marks', async () => {
+    const model = {
+      styles: {
+        textStyles: {
+          textStyleOptions: {
+            heading2: { style: { fontStyle: 'normal' }, isModified: false },
+          },
+        },
+      },
+      pages: [
+        {
+          id: 'p1',
+          contents: [
+            {
+              id: 'c1',
+              type: 'about-section',
+              title: rteDoc([
+                {
+                  text: 'Our ',
+                  marks: [
+                    { type: 'textStyle', attrs: { fontStyle: 'normal' } },
+                  ],
+                },
+                { text: 'Story', marks: [{ type: 'italic' }] },
+              ]),
+              titleStyle: { textStyleType: 'heading2', fontStyle: 'normal' },
+            },
+          ],
+        },
+      ],
+    } as unknown as BrandPageModel;
+
+    const { model: result, errors } = await run(
+      {
+        textStyles: {
+          textStyleOptions: { heading2: { style: { fontStyle: 'italic' } } },
+        },
+      },
+      model,
+    );
+    const content = result.pages[0].contents[0] as unknown as Record<
+      string,
+      unknown
+    >;
+    const [our, story] = runsOf(content.title);
+
+    expect(errors ?? []).toEqual([]);
+    expect(
+      result.styles.textStyles.textStyleOptions.heading2.style.fontStyle,
+    ).toBe('italic');
+    expect(our.marks).toEqual([
+      { type: 'textStyle', attrs: { fontStyle: 'var(--role-font-style)' } },
+    ]);
+    expect(story.marks).toEqual([]);
+    expect(content.titleStyle).toEqual({ textStyleType: 'heading2' });
+  });
+
+  it('button textDecoration none clears the button underline while a paragraph link keeps its own', async () => {
+    const linkRun = {
+      text: 'our menu',
+      marks: [
+        { type: 'link', attrs: { href: 'https://example.com' } },
+        { type: 'underline' },
+      ],
+    };
+    const model = {
+      styles: {
+        textStyles: {
+          textStyleOptions: {
+            button: { style: { textDecoration: 'none' }, isModified: false },
+            paragraph1: { style: {}, isModified: false },
+          },
+        },
+      },
+      pages: [
+        {
+          id: 'p1',
+          contents: [
+            {
+              id: 'c1',
+              type: 'about-section',
+              description: rteDoc([{ text: 'See ' }, linkRun]),
+              descriptionStyle: { textStyleType: 'paragraph1' },
+              buttonText: 'Book now',
+              buttonTextStyle: {
+                textStyleType: 'button',
+                textDecoration: 'underline',
+              },
+            },
+          ],
+        },
+      ],
+    } as unknown as BrandPageModel;
+
+    const { model: result, errors } = await run(
+      {
+        textStyles: {
+          textStyleOptions: {
+            button: { style: { textDecoration: 'none' } },
+          },
+        },
+      },
+      model,
+    );
+    const content = result.pages[0].contents[0] as unknown as Record<
+      string,
+      unknown
+    >;
+
+    expect(errors ?? []).toEqual([]);
+    expect(content.buttonTextStyle).toEqual({ textStyleType: 'button' });
+    expect(runsOf(content.description)[1]).toEqual({
+      type: 'text',
+      ...linkRun,
+    });
+  });
+});