@akinon/pz-theme 2.0.164-rc.1 → 2.0.165-beta.0

package/src/utils/theme-settings-css.ts

@@ -0,0 +1,717 @@
+/**
+ * The storefront side of the redesigned Web Theme Settings.
+ *
+ * The settings page writes a handful of new top-level `theme_settings` keys:
+ * five colour roles (`linkColor`, `headingColor`, `textColor`,
+ * `footerBackgroundColor`, `borderColor`), merchant-added `customColors`, and
+ * typography variants that carry `lineHeight` / `letterSpacing` /
+ * `textTransform` next to the family, weight and size they always had. This
+ * module turns them into:
+ *
+ *  - CSS variables on `:root` (`--theme-link`, `--theme-custom-<id>`,
+ *    `--theme-font-size-<variant>` …), for the server `<style>` and for the
+ *    client, from ONE collector so the two can never disagree;
+ *  - a resolver for `var(--theme-…)` inside block style values, answering
+ *    from the same validated values (emission and resolution stay in parity);
+ *  - element defaults for rich text (`a`, `h1`–`h6`, `p`, `li`, `hr`) and the
+ *    composed footer, emitted ONLY for keys that are explicitly set.
+ *
+ * Two rules every function below honours:
+ *
+ *  1. Nothing is emitted for a theme that never touched the new keys, so an
+ *     existing site renders byte-identically (the builders return '').
+ *  2. Every value is validated before it reaches a `<style>` tag or an inline
+ *     style. `neutralizeStyleTagBreakout` only stops `</style`; a value such
+ *     as `#fff}input{background:url(//x)}` would still close the rule, and a
+ *     theme JSON import or a direct API write bypasses the editor's own
+ *     checks. Invalid values are dropped, never escaped.
+ *
+ * No React and no import of `./index` (which imports this module), so it is
+ * safe to use from server code, client code and the utils barrel alike.
+ */
+import { neutralizeStyleTagBreakout } from './css-safety';
+import { splitPartStyles } from './part-styles';
+
+type ThemeSettingsInput = Record<string, unknown> | null | undefined;
+
+// ---------------------------------------------------------------------------
+// Contract tables
+// ---------------------------------------------------------------------------
+
+/** Colour role storage key → the CSS variable it is published as. */
+export const THEME_COLOR_ROLE_VARIABLES = {
+  linkColor: '--theme-link',
+  headingColor: '--theme-heading',
+  textColor: '--theme-text',
+  footerBackgroundColor: '--theme-footer-background',
+  borderColor: '--theme-border'
+} as const;
+
+export type ThemeColorRoleKey = keyof typeof THEME_COLOR_ROLE_VARIABLES;
+
+const THEME_COLOR_ROLE_KEYS = Object.keys(
+  THEME_COLOR_ROLE_VARIABLES
+) as ThemeColorRoleKey[];
+
+/**
+ * The five colour variables that predate this module. They are written by
+ * `injectThemeColors` and resolved through `THEME_CSS_VARIABLE_MAP`, and they
+ * are never removed: `--theme-primary` has no server `<style>` baseline, so
+ * removing it inline would leave the client without it.
+ */
+const LEGACY_COLOR_VARIABLES: ReadonlySet<string> = new Set([
+  '--theme-primary',
+  '--theme-secondary',
+  '--theme-color3',
+  '--theme-color4',
+  '--theme-background'
+]);
+
+/**
+ * Custom colour ids, editor and storefront alike. `custom-` plus a
+ * non-reusable base-36 stamp, so a deleted colour's id is never handed to a
+ * new one (content still pointing at it would silently re-bind).
+ */
+export const THEME_CUSTOM_COLOR_ID = /^custom-[a-z0-9]+$/;
+
+/** The typography variable prefixes, per variant key K: `${prefix}K`. */
+export const THEME_TYPOGRAPHY_VARIABLE_PREFIXES = {
+  size: '--theme-font-size-',
+  weight: '--theme-font-weight-',
+  lineHeight: '--theme-line-height-',
+  letterSpacing: '--theme-letter-spacing-',
+  transform: '--theme-text-transform-'
+} as const;
+
+/**
+ * Which element each managed variant styles inside rich text. Order is the
+ * emission order. `button`, `menu`, `caption` and custom styles publish their
+ * variables only.
+ */
+const TYPOGRAPHY_ELEMENT_DEFAULTS: ReadonlyArray<readonly [string, string]> = [
+  ['heading01', 'h1'],
+  ['heading02', 'h2'],
+  ['subheading', 'h3'],
+  ['heading04', 'h4'],
+  ['body', 'p'],
+  ['link', 'a']
+];
+
+const TYPOGRAPHY_DEFAULT_KEYS: ReadonlySet<string> = new Set(
+  TYPOGRAPHY_ELEMENT_DEFAULTS.map(([key]) => key)
+);
+
+/** Stamped on a text block's root while element defaults are active. */
+export const THEME_RICH_TEXT_ATTRIBUTE = 'data-pz-rich-text';
+/** Stamped on a block wrapper / section whose root styles set a colour. */
+export const THEME_OWN_COLOR_ATTRIBUTE = 'data-pz-own-color';
+/** Stamped on a block wrapper / section whose root styles set typography. */
+export const THEME_OWN_TYPE_ATTRIBUTE = 'data-pz-own-type';
+
+export const THEME_OWN_COLOR_STYLE_KEYS: readonly string[] = ['color'];
+export const THEME_OWN_TYPE_STYLE_KEYS: readonly string[] = [
+  'font-family',
+  'font-size',
+  'font-weight',
+  'line-height',
+  'letter-spacing',
+  'text-transform'
+];
+
+// ---------------------------------------------------------------------------
+// Validators
+// ---------------------------------------------------------------------------
+
+const HEX_COLOR = /^#(?:[0-9a-f]{3,4}|[0-9a-f]{6}|[0-9a-f]{8})$/i;
+const VARIANT_KEY = /^[a-z0-9-]+$/i;
+const FONT_WEIGHT = /^[1-9]00$/;
+const NUMERIC = /^-?(?:\d+(?:\.\d*)?|\.\d+)(?:px)?$/i;
+const UNSAFE_FAMILY = /[;{}<>\\]|\/\*/;
+
+export type ThemeTextTransform = 'none' | 'uppercase' | 'lowercase';
+const TEXT_TRANSFORMS: ReadonlySet<string> = new Set([
+  'none',
+  'uppercase',
+  'lowercase'
+]);
+
+const SIZE_RANGE = [1, 400] as const;
+const LETTER_SPACING_RANGE = [-50, 50] as const;
+
+const isRecord = (value: unknown): value is Record<string, unknown> =>
+  Boolean(value) && typeof value === 'object' && !Array.isArray(value);
+
+/** `#rgb`, `#rgba`, `#rrggbb` or `#rrggbbaa`, nothing else. */
+export const isThemeHexColor = (value: unknown): value is string =>
+  typeof value === 'string' && HEX_COLOR.test(value.trim());
+
+/** A number, or a numeric string with an optional `px` (`'32px'` → 32). */
+const toFiniteNumber = (value: unknown): number | undefined => {
+  if (typeof value === 'number') {
+    return Number.isFinite(value) ? value : undefined;
+  }
+  if (typeof value !== 'string') return undefined;
+  const trimmed = value.trim();
+  if (!NUMERIC.test(trimmed)) return undefined;
+  const parsed = parseFloat(trimmed);
+  return Number.isFinite(parsed) ? parsed : undefined;
+};
+
+const clamp = (value: number, [min, max]: readonly [number, number]) =>
+  Math.min(max, Math.max(min, value));
+
+/** Three decimals at most, so a stepper's 0.30000000000000004 prints 0.3. */
+const formatNumber = (value: number): string =>
+  String(Number(value.toFixed(3)));
+
+const toPx = (value: number) => `${formatNumber(value)}px`;
+
+const readFontWeight = (value: unknown): string | undefined => {
+  const raw = typeof value === 'number' ? String(value) : value;
+  return typeof raw === 'string' && FONT_WEIGHT.test(raw.trim())
+    ? raw.trim()
+    : undefined;
+};
+
+const readTextTransform = (value: unknown): ThemeTextTransform | undefined =>
+  typeof value === 'string' && TEXT_TRANSFORMS.has(value)
+    ? (value as ThemeTextTransform)
+    : undefined;
+
+/**
+ * The variant's family when it is one a `font-family` declaration can carry
+ * safely. Mirrors `readThemeTypographyFont` (empty and `inherit` mean "no
+ * face") and additionally refuses anything that could end the declaration.
+ */
+const readSafeFamily = (value: unknown): string | undefined => {
+  if (typeof value !== 'string') return undefined;
+  const family = value.trim();
+  if (!family || family === 'inherit' || UNSAFE_FAMILY.test(family)) {
+    return undefined;
+  }
+  return family;
+};
+
+// ---------------------------------------------------------------------------
+// Readers
+// ---------------------------------------------------------------------------
+
+/** One colour role's value, or undefined when unset or not a hex colour. */
+export const readThemeRoleColor = (
+  settings: ThemeSettingsInput,
+  key: ThemeColorRoleKey
+): string | undefined => {
+  const value = settings?.[key];
+  return isThemeHexColor(value) ? value.trim() : undefined;
+};
+
+export interface ThemeCustomColorValue {
+  id: string;
+  value: string;
+}
+
+/** Valid custom colours, deduplicated by id (the first entry wins). */
+export const readThemeCustomColors = (
+  settings: ThemeSettingsInput
+): ThemeCustomColorValue[] => {
+  const entries = settings?.customColors;
+  if (!Array.isArray(entries)) return [];
+
+  const seen = new Set<string>();
+  const colors: ThemeCustomColorValue[] = [];
+
+  entries.forEach((entry) => {
+    if (!isRecord(entry)) return;
+    const { id, value } = entry;
+    if (typeof id !== 'string' || !THEME_CUSTOM_COLOR_ID.test(id)) return;
+    if (seen.has(id) || !isThemeHexColor(value)) return;
+    seen.add(id);
+    colors.push({ id, value: value.trim() });
+  });
+
+  return colors;
+};
+
+export interface ManagedTypographyVariant {
+  key: string;
+  /** Only when a safe family resolves; its variable is `--theme-font-<key>`. */
+  family?: string;
+  /** px, clamped to 1..400 */
+  size?: number;
+  weight?: string;
+  /** px, clamped to 1..400 — its presence is what makes the variant managed */
+  lineHeight: number;
+  /** px, clamped to -50..50 */
+  letterSpacing?: number;
+  transform?: ThemeTextTransform;
+}
+
+/**
+ * The typography variants managed by the redesigned settings: those with a
+ * finite `lineHeight`. Variants saved by the old UI (family/weight/size only,
+ * often a never-applied seed such as heading01 34px/500) are left alone, so
+ * no existing site is retypeset. Deduplicated by key, the first entry wins,
+ * like `readThemeTypographyFont`.
+ */
+export const readManagedTypography = (
+  settings: ThemeSettingsInput
+): ManagedTypographyVariant[] => {
+  const variants = settings?.typography;
+  if (!Array.isArray(variants)) return [];
+
+  const seen = new Set<string>();
+  const managed: ManagedTypographyVariant[] = [];
+
+  variants.forEach((variant) => {
+    if (!isRecord(variant)) return;
+    const { key } = variant;
+    if (typeof key !== 'string' || !VARIANT_KEY.test(key)) return;
+    if (seen.has(key)) return;
+    seen.add(key);
+
+    const lineHeight = toFiniteNumber(variant.lineHeight);
+    if (lineHeight === undefined) return;
+
+    const size = toFiniteNumber(variant.fontSize);
+    const letterSpacing = toFiniteNumber(variant.letterSpacing);
+    const family = readSafeFamily(variant.fontFamily);
+    const weight = readFontWeight(variant.fontWeight);
+    const transform = readTextTransform(variant.textTransform);
+
+    managed.push({
+      key,
+      lineHeight: clamp(lineHeight, SIZE_RANGE),
+      ...(family ? { family } : null),
+      ...(size !== undefined ? { size: clamp(size, SIZE_RANGE) } : null),
+      ...(weight ? { weight } : null),
+      ...(letterSpacing !== undefined
+        ? { letterSpacing: clamp(letterSpacing, LETTER_SPACING_RANGE) }
+        : null),
+      ...(transform ? { transform } : null)
+    });
+  });
+
+  return managed;
+};
+
+// ---------------------------------------------------------------------------
+// Root variables (server <style>, client inline, resolver)
+// ---------------------------------------------------------------------------
+
+export type ThemeRootVariable = readonly [name: string, value: string];
+
+/**
+ * Every `:root` variable the new keys publish, in a stable order: colour
+ * roles, custom colours, then per managed variant its size, weight, line
+ * height, letter spacing and transform. Family variables are NOT included;
+ * they stay with `buildThemeTypographyCss`, whose output is unchanged.
+ */
+export const collectThemeRootVariables = (
+  settings: ThemeSettingsInput
+): ThemeRootVariable[] => {
+  if (!isRecord(settings)) return [];
+
+  const variables: ThemeRootVariable[] = [];
+
+  THEME_COLOR_ROLE_KEYS.forEach((key) => {
+    const value = readThemeRoleColor(settings, key);
+    if (value) variables.push([THEME_COLOR_ROLE_VARIABLES[key], value]);
+  });
+
+  readThemeCustomColors(settings).forEach(({ id, value }) => {
+    variables.push([`--theme-${id}`, value]);
+  });
+
+  const prefixes = THEME_TYPOGRAPHY_VARIABLE_PREFIXES;
+  readManagedTypography(settings).forEach((variant) => {
+    const { key } = variant;
+    if (variant.size !== undefined) {
+      variables.push([`${prefixes.size}${key}`, toPx(variant.size)]);
+    }
+    if (variant.weight) {
+      variables.push([`${prefixes.weight}${key}`, variant.weight]);
+    }
+    variables.push([`${prefixes.lineHeight}${key}`, toPx(variant.lineHeight)]);
+    if (variant.letterSpacing !== undefined) {
+      variables.push([
+        `${prefixes.letterSpacing}${key}`,
+        toPx(variant.letterSpacing)
+      ]);
+    }
+    if (variant.transform) {
+      variables.push([`${prefixes.transform}${key}`, variant.transform]);
+    }
+  });
+
+  return variables;
+};
+
+/**
+ * Settings objects are replaced, never mutated (the server memoizes one per
+ * request; the editor sends a fresh one with every LOAD_THEME/UPDATE_THEME),
+ * so the derived lookups are cached per object.
+ */
+const rootVariableCache = new WeakMap<object, ReadonlyMap<string, string>>();
+
+const rootVariableMap = (
+  settings: Record<string, unknown>
+): ReadonlyMap<string, string> => {
+  const cached = rootVariableCache.get(settings);
+  if (cached) return cached;
+  const map = new Map(collectThemeRootVariables(settings));
+  rootVariableCache.set(settings, map);
+  return map;
+};
+
+/**
+ * The value `var(<name>)` stands for, when `name` is one of the variables
+ * above and its key holds a valid value. Used by `resolveThemeCssVariables`,
+ * so a block style such as `color: var(--theme-link)` is inlined on the
+ * server exactly as the `:root` rule would paint it.
+ */
+export const resolveThemeSettingsVariable = (
+  name: string,
+  settings: ThemeSettingsInput
+): string | undefined => {
+  if (!isRecord(settings) || !name.startsWith('--theme-')) return undefined;
+  return rootVariableMap(settings).get(name);
+};
+
+/**
+ * Whether `name` is one of the typography metric variables. They share the
+ * `--theme-font-` prefix with the family variables, so the family lookup has
+ * to skip them: `--theme-font-size-body` is the body's size, never the family
+ * of a variant keyed `size-body`.
+ */
+export const isThemeTypographyMetricVariable = (name: string): boolean =>
+  Object.values(THEME_TYPOGRAPHY_VARIABLE_PREFIXES).some((prefix) =>
+    name.startsWith(prefix)
+  );
+
+/** `:root{…}` with every variable above, or '' when there is none. */
+export const buildThemeRoleVariablesCss = (
+  settings: ThemeSettingsInput
+): string => {
+  const variables = collectThemeRootVariables(settings);
+  if (!variables.length) return '';
+  return neutralizeStyleTagBreakout(
+    `:root{${variables.map(([name, value]) => `${name}:${value}`).join(';')}}`
+  );
+};
+
+/**
+ * Brings `style` (the document element's inline style) in line with `next`:
+ * sets every variable in it and removes the ones written last time that are
+ * gone now (a deleted custom colour, a role the merchant hid). Returns the
+ * new written set for the caller to keep. The five legacy colour variables
+ * are never written or removed here.
+ *
+ * Removal is safe on a page whose placeholders carry different settings
+ * (draft mode): each placeholder's server `<style>` stays in the cascade as
+ * the baseline, and inline values only ever override it.
+ */
+export const syncThemeRootVariables = (
+  style: Pick<CSSStyleDeclaration, 'setProperty' | 'removeProperty'>,
+  next: ReadonlyArray<ThemeRootVariable>,
+  previous: ReadonlySet<string>
+): Set<string> => {
+  const variables = new Map<string, string>();
+  next.forEach(([name, value]) => {
+    if (!LEGACY_COLOR_VARIABLES.has(name)) variables.set(name, value);
+  });
+
+  previous.forEach((name) => {
+    if (!variables.has(name) && !LEGACY_COLOR_VARIABLES.has(name)) {
+      style.removeProperty(name);
+    }
+  });
+  variables.forEach((value, name) => style.setProperty(name, value));
+
+  return new Set(variables.keys());
+};
+
+// ---------------------------------------------------------------------------
+// Element defaults
+// ---------------------------------------------------------------------------
+
+const textDefaultsCache = new WeakMap<object, boolean>();
+
+/**
+ * Whether any rich-text element default is active: a valid text, heading,
+ * link or border colour, or a managed heading01/heading02/subheading/
+ * heading04/body/link variant. Gates the `data-pz-*` markers, so a site that
+ * never set these keys renders without a single new attribute.
+ */
+export const hasThemeTextDefaults = (settings: ThemeSettingsInput): boolean => {
+  if (!isRecord(settings)) return false;
+  const cached = textDefaultsCache.get(settings);
+  if (cached !== undefined) return cached;
+
+  const active =
+    Boolean(
+      readThemeRoleColor(settings, 'textColor') ||
+        readThemeRoleColor(settings, 'headingColor') ||
+        readThemeRoleColor(settings, 'linkColor') ||
+        readThemeRoleColor(settings, 'borderColor')
+    ) ||
+    readManagedTypography(settings).some(({ key }) =>
+      TYPOGRAPHY_DEFAULT_KEYS.has(key)
+    );
+
+  textDefaultsCache.set(settings, active);
+  return active;
+};
+
+/** Rich text rendered by a theme placeholder (a text block's root). */
+const RICH_TEXT = `:where(.theme-placeholder [${THEME_RICH_TEXT_ATTRIBUTE}])`;
+/**
+ * An inline colour inside the rich text. The editor's text-colour tool wraps
+ * its selection in `<span style="color: …">`, around whole paragraphs or a
+ * heading, or around a link; older and pasted markup may use `<font color>`.
+ * A default set on the p, h2 or a inside would replace the colour it
+ * inherits from there.
+ */
+const INLINE_COLOR = `[${THEME_RICH_TEXT_ATTRIBUTE}] :is([style^="color"],[style*=";color"],[style*="; color"],font[color])`;
+/** The same for inline typography, which only pasted or older markup carries. */
+const INLINE_TYPE = `[${THEME_RICH_TEXT_ATTRIBUTE}] :is([style*="font-size"],[style*="font-family"],[style*="font-weight"],[style*="font:"],[style*="line-height"],[style*="letter-spacing"],[style*="text-transform"],font[size],font[face])`;
+/** Not inside an element, or an inline style, that set its own colour. */
+const NOT_OWN_COLOR = `:not(:where([${THEME_OWN_COLOR_ATTRIBUTE}] *,${INLINE_COLOR} *))`;
+/** Not inside an element, or an inline style, that set its own typography. */
+const NOT_OWN_TYPE = `:not(:where([${THEME_OWN_TYPE_ATTRIBUTE}] *,${INLINE_TYPE} *))`;
+/** A link inside a heading is set in the heading's size, not the Link style's. */
+const NOT_IN_HEADING = ':not(:where(:is(h1,h2,h3,h4,h5,h6) *))';
+const FOOTER = ':where(.theme-placeholder[data-placeholder="footer"])';
+
+/** Keywords, not names: quoted, `sans-serif` would name a font. */
+const GENERIC_FONT_FAMILIES: ReadonlySet<string> = new Set([
+  'serif',
+  'sans-serif',
+  'monospace',
+  'cursive',
+  'fantasy',
+  'system-ui',
+  'ui-serif',
+  'ui-sans-serif',
+  'ui-monospace',
+  'ui-rounded',
+  'emoji',
+  'math',
+  'fangsong'
+]);
+
+/**
+ * A validated family as a `font-family` value with every name quoted. An
+ * unquoted name has to be a run of identifiers, so `Source Sans 3`, `Exo 2`
+ * or `Press Start 2P` would leave the declaration invalid and the text in
+ * the inherited face. A stack (`Roboto, sans-serif`, written by the old font
+ * select) keeps its generic family a keyword. The `--theme-font-<key>`
+ * variable is left as it always was, so existing output does not change.
+ */
+const toFontFamilyValue = (family: string): string | undefined => {
+  const names = family
+    .split(',')
+    .map((name) => name.replace(/["']/g, '').trim())
+    .filter(Boolean)
+    .map((name) =>
+      GENERIC_FONT_FAMILIES.has(name.toLowerCase())
+        ? name.toLowerCase()
+        : `"${name}"`
+    );
+  return names.length ? names.join(',') : undefined;
+};
+
+const typographyDeclarations = (variant: ManagedTypographyVariant): string => {
+  const { key } = variant;
+  const prefixes = THEME_TYPOGRAPHY_VARIABLE_PREFIXES;
+  const family = variant.family ? toFontFamilyValue(variant.family) : '';
+  return [
+    family ? `font-family:${family}` : '',
+    variant.size !== undefined ? `font-size:var(${prefixes.size}${key})` : '',
+    variant.weight ? `font-weight:var(${prefixes.weight}${key})` : '',
+    `line-height:var(${prefixes.lineHeight}${key})`,
+    variant.letterSpacing !== undefined
+      ? `letter-spacing:var(${prefixes.letterSpacing}${key})`
+      : '',
+    variant.transform ? `text-transform:var(${prefixes.transform}${key})` : ''
+  ]
+    .filter(Boolean)
+    .join(';');
+};
+
+/**
+ * The global defaults, for the keys that are set and nothing else.
+ *
+ * Every element rule has specificity exactly (0,0,1): it beats Tailwind v3's
+ * unlayered preflight on source order (this `<style>` is in the body, after
+ * the head CSS), beats Tailwind v4's layered preflight, and loses to any
+ * class and to the block CSS. It is scoped to rich text because rich text
+ * carries no utility classes; aimed at bare `.theme-placeholder` descendants
+ * it would override pz-theme's own sections, brand sections, the portaled
+ * checkout and the designer chrome. The root-level rules (text colour and
+ * body typography on the rich-text root, the footer background) are (0,0,0).
+ *
+ * The `data-pz-own-*` exclusions keep authored values: a heading inside a
+ * section or group that set its own colour keeps inheriting it, and a text
+ * block that set its own font size is not retypeset. Inline colour and
+ * typography inside the rich text are kept the same way.
+ */
+export const buildThemeElementDefaultsCss = (
+  settings: ThemeSettingsInput
+): string => {
+  if (!isRecord(settings)) return '';
+
+  const rules: string[] = [];
+  const vars = THEME_COLOR_ROLE_VARIABLES;
+
+  if (readThemeRoleColor(settings, 'textColor')) {
+    rules.push(
+      `${RICH_TEXT}${NOT_OWN_COLOR},${RICH_TEXT} :is(p,li)${NOT_OWN_COLOR}{color:var(${vars.textColor})}`
+    );
+  }
+  if (readThemeRoleColor(settings, 'headingColor')) {
+    rules.push(
+      `${RICH_TEXT} :is(h1,h2,h3,h4,h5,h6)${NOT_OWN_COLOR}{color:var(${vars.headingColor})}`
+    );
+  }
+  if (readThemeRoleColor(settings, 'linkColor')) {
+    rules.push(`${RICH_TEXT} a${NOT_OWN_COLOR}{color:var(${vars.linkColor})}`);
+  }
+  if (readThemeRoleColor(settings, 'borderColor')) {
+    rules.push(`${RICH_TEXT} hr{border-color:var(${vars.borderColor})}`);
+  }
+  if (readThemeRoleColor(settings, 'footerBackgroundColor')) {
+    rules.push(
+      `${FOOTER}{background-color:var(${vars.footerBackgroundColor})}`
+    );
+  }
+
+  const managed = new Map(
+    readManagedTypography(settings).map((variant) => [variant.key, variant])
+  );
+  TYPOGRAPHY_ELEMENT_DEFAULTS.forEach(([key, element]) => {
+    const variant = managed.get(key);
+    if (!variant) return;
+    const selector =
+      key === 'body'
+        ? `${RICH_TEXT}${NOT_OWN_TYPE},${RICH_TEXT} ${element}${NOT_OWN_TYPE}`
+        : key === 'link'
+        ? `${RICH_TEXT} ${element}${NOT_IN_HEADING}${NOT_OWN_TYPE}`
+        : `${RICH_TEXT} ${element}${NOT_OWN_TYPE}`;
+    rules.push(`${selector}{${typographyDeclarations(variant)}}`);
+  });
+
+  return rules.length ? neutralizeStyleTagBreakout(rules.join('')) : '';
+};
+
+// ---------------------------------------------------------------------------
+// Authored-style markers
+// ---------------------------------------------------------------------------
+
+const toKebabCase = (key: string): string =>
+  key.includes('-')
+    ? key
+    : key.replace(/([a-z])([A-Z])/g, '$1-$2').toLowerCase();
+
+const isAuthoredScalar = (value: unknown): boolean =>
+  (typeof value === 'string' && value.trim() !== '') ||
+  (typeof value === 'number' && Number.isFinite(value));
+
+/** A scalar, or a per-breakpoint map with at least one authored value. */
+const isAuthoredStyleValue = (value: unknown): boolean =>
+  isAuthoredScalar(value) ||
+  (isRecord(value) && Object.values(value).some(isAuthoredScalar));
+
+const hasAuthoredKey = (
+  bucket: Record<string, unknown>,
+  keys: readonly string[]
+): boolean =>
+  Object.entries(bucket).some(
+    ([key, value]) =>
+      keys.includes(toKebabCase(key)) && isAuthoredStyleValue(value)
+  );
+
+/**
+ * Whether a block's or section's ROOT styles set any of `keys` (kebab-case),
+ * at any breakpoint, at rest or in a root state (`:hover/color`,
+ * `:scrolled/color`): the state rule paints the element too, and a default
+ * on the rich text inside would stop it reaching the text. Part keys
+ * (`label/color`) do not count: they style another element (see
+ * `themeOwnPartStyleAttributes` for a part that holds child blocks).
+ */
+export const hasAuthoredRootStyle = (
+  styles: unknown,
+  keys: readonly string[]
+): boolean => {
+  if (!isRecord(styles)) return false;
+  const { root, rootStates } = splitPartStyles(styles);
+  return (
+    hasAuthoredKey(root, keys) ||
+    rootStates.some((bucket) => hasAuthoredKey(bucket.styles, keys))
+  );
+};
+
+const ownStyleMarkers = (
+  ownColor: boolean,
+  ownType: boolean
+): Record<string, string> | null =>
+  ownColor || ownType
+    ? {
+        ...(ownColor ? { [THEME_OWN_COLOR_ATTRIBUTE]: '' } : null),
+        ...(ownType ? { [THEME_OWN_TYPE_ATTRIBUTE]: '' } : null)
+      }
+    : null;
+
+/**
+ * Text colour or typography a renderer paints on an element itself, where no
+ * style object shows it (a class list such as `uppercase tracking-[0.12em]`).
+ */
+export interface ThemeOwnTextStyle {
+  color?: boolean;
+  type?: boolean;
+}
+
+/**
+ * The `data-pz-own-color` / `data-pz-own-type` attributes for an element with
+ * these root styles (or painted as `owned` says), or null. Null whenever the
+ * theme has no rich-text defaults, so untouched sites gain no attribute.
+ */
+export const themeOwnStyleAttributes = (
+  styles: unknown,
+  settings: ThemeSettingsInput,
+  owned?: ThemeOwnTextStyle
+): Record<string, string> | null => {
+  if (!hasThemeTextDefaults(settings)) return null;
+
+  return ownStyleMarkers(
+    owned?.color === true ||
+      hasAuthoredRootStyle(styles, THEME_OWN_COLOR_STYLE_KEYS),
+    owned?.type === true ||
+      hasAuthoredRootStyle(styles, THEME_OWN_TYPE_STYLE_KEYS)
+  );
+};
+
+/**
+ * The same attributes for one PART of a block, for a renderer whose part
+ * element holds child blocks (an accordion's header row and panel). A part
+ * colour or typography, at rest or in a state (`header/color`,
+ * `header/open/color`), paints that element, so the child text blocks have
+ * to keep inheriting it.
+ */
+export const themeOwnPartStyleAttributes = (
+  styles: unknown,
+  part: string,
+  settings: ThemeSettingsInput
+): Record<string, string> | null => {
+  if (!hasThemeTextDefaults(settings) || !isRecord(styles)) return null;
+
+  const buckets = splitPartStyles(styles)
+    .parts.filter((bucket) => bucket.part === part)
+    .map((bucket) => bucket.styles);
+
+  return ownStyleMarkers(
+    buckets.some((bucket) =>
+      hasAuthoredKey(bucket, THEME_OWN_COLOR_STYLE_KEYS)
+    ),
+    buckets.some((bucket) => hasAuthoredKey(bucket, THEME_OWN_TYPE_STYLE_KEYS))
+  );
+};