Skip to content

An open source design system that's fully customizable and agent ready

TypeScript
67.4 KB
Raw Blame
// Copyright (c) Meta Platforms, Inc. and affiliates.

/**
 * @file Theme CSS generation utilities
 *
 * Shared logic for generating CSS rules from a resolved theme definition,
 * including source-scoped semantic role defaults and one component-leaf lowering
 * path for root, adaptation, and media-surface values plus condition-correct
 * Heading weight precedence guards.
 * Built adaptation metadata resolves against the same root component defaults
 * as defineTheme, so scale-only rules do not reset authored component styles.
 * Used by both the runtime path (Theme injects <style>) and the build
 * path (`astryx theme build` pre-compiles to CSS files).
 *
 * Every consumer-supplied declaration is checked by declarationBoundary.ts
 * before it is emitted, so a value can never end its declaration or rule
 * early. A refused declaration is dropped and reported in the supplied
 * warnings array (build receipts), or through `console.warn` (runtime).
 *
 * Extracted from defineTheme.ts to reduce cyclomatic complexity and provide
 * a clear single-responsibility module for CSS generation.
 *
 * @input DefinedTheme (resolved theme object from defineTheme), optional warnings array
 * @output CSS rule strings, split by layer (component vs prose), and warning text
 *   for each dropped declaration
 * @position packages/core/src/theme/generateThemeRules.ts
 */

import type {ComponentStyleMap, DefinedTheme} from './defineTheme';
import {
  normalizeThemeAdaptations,
  resolveThemeAdaptationRules,
  type ResolvedThemeAdaptationRule,
} from './themeAdaptations';
import {parseStyleKey} from '../utils/parseStyleKey';
import {getDerivedVars} from './derivedVarRegistry';
import {STATUS_NAMES, deriveStatusRoleTokens} from './statusRoleDerivation';
import {cssVar, classPrefix, dataAttrNamespace} from '../naming';
import {
  analyzeDeclarationValue,
  canonicalizeDeclarationName,
  checkDeclarationName,
  checkDeclarationValue,
} from './declarationBoundary';
import {readerTextSizeEntries} from './dynamicType';
import {PRESS_BELIEVED_SELECTOR} from '../privateAttributes/press';

/**
 * Theme @scope selectors.
 *
 * Theme CSS is @scope'd to the theme-name data attribute that Theme writes
 * (`data-astryx-theme`).
 *
 * @example themeScopeStart('mytheme')
 *   -> '[data-astryx-theme="mytheme"]'
 */
function themeScopeStart(name: string): string {
  return `[data-${dataAttrNamespace}-theme="${name}"]`;
}

/** Scope limit matching the theme attribute (nested-theme boundary). */
const THEME_SCOPE_TO = `[data-${dataAttrNamespace}-theme]`;

/** Media-surface selector, e.g. for [data-astryx-media="dark"]. */
function mediaSelector(surface: string): string {
  return `[data-${dataAttrNamespace}-media="${surface}"]`;
}

/** Component base-class selector, e.g. '.astryx-button'. */
function componentClassSelector(component: string, suffix: string): string {
  return `.${classPrefix}-${component}${suffix}`;
}

type MediaSurface = 'dark' | 'light';

/** Scope a component selector to an inverted media surface when requested. */
function componentSelector(
  component: string,
  suffix: string,
  surface?: MediaSurface,
): string {
  const selector = componentClassSelector(component, suffix);
  return surface ? `:is(${mediaSelector(surface)}) :is(${selector})` : selector;
}

/**
 * Guard appended to a themed `:hover` rule so it cannot match a disabled
 * element.
 *
 * A theme authoring `':hover': {backgroundColor: …}` is describing the
 * enabled control; `:hover` on its own would paint that background on a
 * disabled one too, because browsers suppress a disabled control's events,
 * not its hover styling. `:where()` contributes no specificity, so a themed
 * hover rule still weighs exactly what it weighed before.
 *
 * Mirrors the `@astryx/no-hover-on-disabled` lint rule, which enforces the
 * same guard on the components' own StyleX styles.
 */
const HOVER_DISABLED_GUARD = ':where(:not(:disabled,[aria-disabled="true"]))';

/**
 * Append a pseudo-class to every selector in a comma-separated selector list.
 *
 * Selector helpers may emit comma-separated lists. CSS does not distribute a
 * trailing pseudo over selector lists, so `${list}:hover` would only target the
 * final selector. Rewrite each item so the pseudo applies to all of them.
 *
 * A `:hover` pseudo also picks up the disabled guard. A pseudo-ELEMENT has to
 * end the selector, so the guard is spliced in before it.
 */
function appendPseudoToSelectorList(selector: string, pseudo: string): string {
  const parts: string[] = [];
  let depth = 0;
  let start = 0;

  for (let i = 0; i < selector.length; i++) {
    const char = selector[i];
    if (char === '(') {
      depth++;
    } else if (char === ')') {
      depth = Math.max(0, depth - 1);
    } else if (char === ',' && depth === 0) {
      parts.push(selector.slice(start, i).trim());
      start = i + 1;
    }
  }
  parts.push(selector.slice(start).trim());

  const guarded = guardHoverPseudo(pseudo);

  return parts.map(part => `${part}${guarded}`).join(', ');
}

/**
 * The touch press model (utils/interactionOverlay.stylex.ts, pressFeedback.ts).
 * A mouse keeps `:active`. Under a coarse primary pointer, the press
 * controller marks a press it believes. A finger then paints no press on the
 * touch or through a scroll.
 */
const COARSE_POINTER_QUERY = '(pointer: coarse)';
const ACTIVE_PSEUDO = /:active(?![-\w])/g;

/**
 * The rules for one themed pseudo-class override. A themed `:active` follows
 * the press model: the `:active` rule applies only off a coarse pointer, and
 * under one the press attribute takes `:active`'s place.
 */
function pseudoRules(
  baseSelector: string,
  pseudo: string,
  declarations: string,
): string[] {
  if (!new RegExp(ACTIVE_PSEUDO.source).test(pseudo)) {
    return [
      `  ${appendPseudoToSelectorList(baseSelector, pseudo)} {\n${declarations}\n  }`,
    ];
  }
  const pressed = pseudo.replace(ACTIVE_PSEUDO, PRESS_BELIEVED_SELECTOR);
  return [
    `  @media not all and ${COARSE_POINTER_QUERY} {\n  ${appendPseudoToSelectorList(baseSelector, pseudo)} {\n${declarations}\n  }\n  }`,
    `  @media ${COARSE_POINTER_QUERY} {\n  ${appendPseudoToSelectorList(baseSelector, pressed)} {\n${declarations}\n  }\n  }`,
  ];
}

/** Insert the disabled guard into a `:hover` pseudo, keeping any pseudo-element last. */
function guardHoverPseudo(pseudo: string): string {
  if (!/^:hover(?![-\w])/.test(pseudo) || pseudo.includes('[aria-disabled')) {
    return pseudo;
  }
  const pseudoElement = pseudo.indexOf('::');
  return pseudoElement === -1
    ? pseudo + HOVER_DISABLED_GUARD
    : pseudo.slice(0, pseudoElement) +
        HOVER_DISABLED_GUARD +
        pseudo.slice(pseudoElement);
}

// =============================================================================
// Types
// =============================================================================

/**
 * Structured output from generateThemeRulesSplit.
 * Separates prose element defaults from component/token overrides
 * so callers can place them in different CSS layers.
 */
export interface ThemeRulesSplit {
  /** Token overrides + component .astryx-* overrides + prop-level color rules */
  component: string[];
  /** Prose element defaults (h1-h6, p, small, code, hr) — belongs in reset layer */
  prose: string[];
}

/**
 * Output from generateThemeCSS — two CSS blocks for different layers.
 */
export interface ThemeCSSOutput {
  /**
   * Prose element defaults (p, h1-h6, small, code, hr) scoped to the theme.
   * Should be injected into @layer reset — lowest priority, any class wins.
   * Empty string if no prose rules.
   */
  prose: string;
  /**
   * Token overrides + component target/data-attribute overrides scoped to the theme.
   * Should be injected into @layer astryx-theme — above StyleX layers so
   * theme component overrides take effect. Empty string if no rules.
   */
  component: string;
}

// =============================================================================
// Internal helpers
// =============================================================================

/** Convert camelCase CSS property to kebab-case */
function toKebabCase(str: string): string {
  return str.replace(/[A-Z]/g, m => `-${m.toLowerCase()}`);
}

/** Padding properties that trigger container token mapping */
const PADDING_PROPS = new Set([
  'padding',
  'paddingBlock',
  'paddingInline',
  'paddingBlockStart',
  'paddingBlockEnd',
  'paddingInlineStart',
  'paddingInlineEnd',
]);

/**
 * Physical block-axis longhands, and the logical longhand each one *is* in
 * every horizontal writing mode. Normalizing them costs no direction
 * assumption, which is why they can join the container expansion.
 *
 * `paddingLeft`/`paddingRight` are deliberately absent. They are
 * direction-relative — left is inline-start in LTR and inline-end in RTL — and
 * the expansion's tokens are consumed by logical properties, so mapping them
 * would put the padding on the opposite edge in RTL. They keep their physical
 * meaning and land on the element as `padding-left`/`padding-right`; the cost
 * is that a component's internals cannot see them.
 */
const PHYSICAL_BLOCK_PADDING_PROPS: Record<string, string> = {
  paddingTop: 'paddingBlockStart',
  paddingBottom: 'paddingBlockEnd',
};

/**
 * Every padding spelling the container expansion consumes. Kept separate from
 * PADDING_PROPS, which also routes longhands to `vars`-style derived entries —
 * those carry one value for the whole box, so a single physical edge must not
 * reach them.
 */
const CONTAINER_PADDING_PROPS = new Set([
  ...PADDING_PROPS,
  ...Object.keys(PHYSICAL_BLOCK_PADDING_PROPS),
]);

interface ParsedPadding {
  blockStart?: string;
  blockEnd?: string;
  inline?: string;
  inlineStart?: string;
  inlineEnd?: string;
}

/**
 * Parse CSS padding shorthand/longhand into block/inline values.
 * Supports 1-3 value shorthands, logical properties, and the physical block
 * longhands normalized by PHYSICAL_BLOCK_PADDING_PROPS.
 */
function parsePadding(props: [string, string][]): ParsedPadding {
  const result: ParsedPadding = {};

  for (const [rawProp, value] of props) {
    const prop = PHYSICAL_BLOCK_PADDING_PROPS[rawProp] ?? rawProp;
    switch (prop) {
      case 'padding': {
        const parts = value.trim().split(/\s+/);
        if (parts.length === 1) {
          result.blockStart = parts[0];
          result.blockEnd = parts[0];
          result.inline = parts[0];
        } else if (parts.length === 2) {
          result.blockStart = parts[0];
          result.blockEnd = parts[0];
          result.inline = parts[1];
        } else if (parts.length >= 3) {
          result.blockStart = parts[0];
          result.inline = parts[1];
          result.blockEnd = parts[2];
        }
        break;
      }
      case 'paddingBlock': {
        const parts = value.trim().split(/\s+/);
        result.blockStart = parts[0];
        result.blockEnd = parts[1] ?? parts[0];
        break;
      }
      case 'paddingInline': {
        const parts = value.trim().split(/\s+/);
        if (parts.length === 1) {
          result.inline = parts[0];
        } else {
          result.inlineStart = parts[0];
          result.inlineEnd = parts[1];
        }
        break;
      }
      case 'paddingBlockStart':
        result.blockStart = value;
        break;
      case 'paddingBlockEnd':
        result.blockEnd = value;
        break;
      case 'paddingInlineStart':
        result.inlineStart = value;
        break;
      case 'paddingInlineEnd':
        result.inlineEnd = value;
        break;
    }
  }

  return result;
}

/**
 * Expand parsed padding into component-scoped public tokens.
 *
 * Emits the rebranded --astryx-<component>-padding tokens (shorthand +
 * directional overrides), e.g.:
 *   --astryx-card-padding: 20px
 *   --astryx-card-padding-inline: 20px
 *   --astryx-card-padding-block-start: 20px
 *   --astryx-card-padding-block-end: 20px
 *
 * The component reads these with an inverted fallback chain
 * (var(--astryx-*, default)). The container.stylex.ts default styles read
 * these via var() fallbacks,
 * so the theme CSS sets the value and the component picks it up through
 * CSS custom property cascade — no layer competition with StyleX output.
 */
function expandContainerPadding(
  component: string,
  parsed: ParsedPadding,
  resetInheritedSpecificity = false,
): [string, string][] {
  const prefix = cssVar(`${component}-padding`);
  const tokens: [string, string][] = [];

  // Resolve effective inline values (inlineStart/End override inline)
  const effectiveInlineStart = parsed.inlineStart ?? parsed.inline;
  const effectiveInlineEnd = parsed.inlineEnd ?? parsed.inline;
  const inlineSymmetric =
    effectiveInlineStart != null &&
    effectiveInlineEnd != null &&
    effectiveInlineStart === effectiveInlineEnd;

  // If all sides are the same, emit the shorthand token only
  const allSame =
    inlineSymmetric &&
    parsed.blockStart != null &&
    parsed.blockEnd != null &&
    effectiveInlineStart === parsed.blockStart &&
    parsed.blockStart === parsed.blockEnd;

  if (allSame) {
    tokens.push([prefix, effectiveInlineStart ?? '']);
  } else {
    // Directional tokens
    if (parsed.inlineStart != null || parsed.inlineEnd != null) {
      // Asymmetric inline — emit start and end separately
      if (effectiveInlineStart != null) {
        tokens.push([`${prefix}-inline-start`, effectiveInlineStart]);
      }
      if (effectiveInlineEnd != null) {
        tokens.push([`${prefix}-inline-end`, effectiveInlineEnd]);
      }
    } else if (parsed.inline != null) {
      tokens.push([`${prefix}-inline`, parsed.inline]);
    }
    if (parsed.blockStart != null) {
      tokens.push([`${prefix}-block-start`, parsed.blockStart]);
    }
    if (parsed.blockEnd != null) {
      tokens.push([`${prefix}-block-end`, parsed.blockEnd]);
    }
  }

  if (resetInheritedSpecificity) {
    const emitted = new Set(tokens.map(([name]) => name));
    const moreSpecific = emitted.has(prefix)
      ? [
          `${prefix}-inline`,
          `${prefix}-inline-start`,
          `${prefix}-inline-end`,
          `${prefix}-block-start`,
          `${prefix}-block-end`,
        ]
      : emitted.has(`${prefix}-inline`)
        ? [`${prefix}-inline-start`, `${prefix}-inline-end`]
        : [];
    for (const name of moreSpecific) {
      if (!emitted.has(name)) {
        // `initial` makes a custom property guaranteed-invalid so var() follows
        // its fallback, clearing a more-specific declaration from a root rule.
        tokens.push([name, 'initial']);
      }
    }
  }

  return tokens;
}

// =============================================================================
// Declaration assembly: a declaration always stays one declaration
// =============================================================================

type DiagnosticSink = (message: string) => void;

const warnToConsole: DiagnosticSink = message => {
  console.warn(`[astryx theme] ${message}`);
};

/** Build receipts collect warning text; runtime callers warn by default. */
function diagnosticSink(warnings: string[] | undefined): DiagnosticSink {
  return warnings ? message => warnings.push(message) : warnToConsole;
}

/** Shorten an authored value for a one-line message. */
function previewValue(value: string): string {
  const oneLine = JSON.stringify(value);
  return oneLine.length > 80 ? `${oneLine.slice(0, 77)}..."` : oneLine;
}

function reportDrop(
  sink: DiagnosticSink,
  property: string,
  value: string,
  location: string,
  reason: string,
): void {
  sink(
    `dropped "${property}" in ${location}: ${reason} (value: ${previewValue(value)})`,
  );
}

/**
 * True when `name: value;` stays exactly one declaration; otherwise reports
 * the drop and returns false. Both checks follow CSS syntax, so valid CSS a
 * browser keeps inside one declaration (a `data:` URI, `Gill\ Sans`, a closed
 * comment, a vendor-prefixed property) is never refused; see
 * declarationBoundary.ts for the rules.
 */
function acceptDeclaration(
  property: string,
  value: string,
  location: string,
  sink: DiagnosticSink,
): boolean {
  const reason = checkDeclarationName(property) ?? checkDeclarationValue(value);
  if (reason === null) {
    return true;
  }
  reportDrop(sink, property, value, location, reason);
  return false;
}

/**
 * Assemble `prop: value;` lines, dropping (and reporting) any entry whose
 * property or value could not stay a single declaration. Theme definitions
 * are code, but apps do assemble them from stored input (brand colors,
 * white-labeling), so the generated stylesheet must never extend beyond the
 * declarations it means to emit.
 */
function joinDeclarations(
  entries: [string, string][],
  location: string,
  sink: DiagnosticSink,
  mapProp: (prop: string) => string = p => p,
): string {
  const lines: string[] = [];
  for (const [rawProp, rawValue] of entries) {
    // Legacy unenrolled tokens retain non-string values. Scan the same text
    // interpolation has always emitted, without changing the normalized theme.
    const value = stringifyTokenValue(rawValue);
    const prop = mapProp(rawProp);
    if (acceptDeclaration(prop, value, location, sink)) {
      lines.push(`    ${prop}: ${value};`);
    }
  }
  return lines.join('\n');
}

/**
 * Public tokens whose canonical default references another public token: the
 * status roles and `--duration-exit`. StyleX owns the document defaults. A
 * theme that authors a source repeats its omitted token at the theme root so
 * nested Theme regions bind the alias locally without changing authored-token
 * metadata.
 *
 * Conditional scopes repeat an omitted alias only when the source changes on
 * that scope. Explicit adaptation role writes are replayed after generated
 * aliases (and on media descendants) so authored role precedence survives
 * overlapping conditions without disabling the alias in non-matching states.
 */
const SCOPED_REFERENCE_DEFAULTS: ReadonlyArray<
  readonly [role: string, source: string]
> = [
  ['--color-text-info', '--color-text-blue'],
  ['--color-text-success', '--color-text-green'],
  ['--color-text-warning', '--color-text-yellow'],
  ['--color-text-error', '--color-text-red'],
  ['--color-on-info-muted', '--color-text-blue'],
  ['--color-on-success-muted', '--color-text-green'],
  ['--color-on-warning-muted', '--color-text-yellow'],
  ['--color-on-error-muted', '--color-text-red'],
  // Icon and border roles follow the text role, set or derived (INV17).
  ['--color-icon-info', '--color-text-info'],
  ['--color-icon-success', '--color-text-success'],
  ['--color-icon-warning', '--color-text-warning'],
  ['--color-icon-error', '--color-text-error'],
  ['--color-border-info', '--color-text-info'],
  ['--color-border-success', '--color-text-success'],
  ['--color-border-warning', '--color-text-warning'],
  ['--color-border-error', '--color-text-error'],
  ['--duration-exit', '--duration-fast'],
];

const SCOPED_REFERENCE_SOURCES = new Map(SCOPED_REFERENCE_DEFAULTS);

/** Colours INV17's derivation measures; a scope that sets one re-derives. */
const STATUS_MEASURED =
  /^--color-(?:info|success|warning|error|on-|background-surface|background-card)/;

const STATUS_ROLE_ORDER = new Map(
  SCOPED_REFERENCE_DEFAULTS.map(([role], index) => [role, index]),
);

type TokenValues = Record<string, unknown>;

function stringifyTokenValue(value: unknown): string {
  if (typeof value === 'string') {
    return value;
  }
  // Preserve the exact JavaScript interpolation behavior legacy themes received
  // before declaration analysis accepted non-string token values.
  return String(value);
}

interface TokenCascadeState {
  values: TokenValues;
  important: Set<string>;
}

function assignTokenCascade(
  state: TokenCascadeState,
  ...tokenSets: ReadonlyArray<TokenValues | undefined>
): void {
  for (const tokens of tokenSets) {
    for (const [rawToken, rawValue] of Object.entries(tokens ?? {})) {
      const token = canonicalizeDeclarationName(rawToken);
      const value = stringifyTokenValue(rawValue);
      const analysis = analyzeDeclarationValue(value);
      // Match joinDeclarations: declarations that cannot be emitted never
      // participate in the browser cascade this safety model validates.
      if (token === null || analysis.reason !== null) {
        continue;
      }
      if (state.important.has(token) && !analysis.important) {
        continue;
      }
      state.values[token] = value;
      if (analysis.important) {
        state.important.add(token);
      } else {
        state.important.delete(token);
      }
    }
  }
}

function createTokenCascade(
  ...tokenSets: ReadonlyArray<TokenValues | undefined>
): TokenCascadeState {
  const state: TokenCascadeState = {values: {}, important: new Set()};
  assignTokenCascade(state, ...tokenSets);
  return state;
}

/** Check whether one candidate value closes a cycle through its own role. */
function tokenValuesWouldHaveCycleWithValue(
  tokens: TokenValues,
  relevantToken: string,
  candidateValue: string,
): boolean {
  const stack = [...analyzeDeclarationValue(candidateValue).references];
  const visited = new Set<string>();
  while (stack.length > 0) {
    const token = stack.pop();
    if (token === undefined) {
      continue;
    }
    if (token === relevantToken) {
      return true;
    }
    if (
      visited.has(token) ||
      !Object.prototype.hasOwnProperty.call(tokens, token)
    ) {
      continue;
    }
    visited.add(token);
    for (const reference of analyzeDeclarationValue(
      stringifyTokenValue(tokens[token]),
    ).references) {
      if (
        reference === relevantToken ||
        Object.prototype.hasOwnProperty.call(tokens, reference)
      ) {
        stack.push(reference);
      }
    }
  }
  return false;
}

const WIDTH_CELL_RANK = {
  sm: 1,
  md: 2,
  lg: 3,
  xl: 4,
  '2xl': 5,
} as const;

function adaptationConditionMatchesCell(
  condition: ResolvedThemeAdaptationRule['when'],
  widthRank: number,
  pointer: 'coarse' | 'fine' | 'none',
  contrast: 'more' | 'less' | 'no-preference' | 'custom',
  motion: 'reduce' | 'no-preference',
): boolean {
  const from = condition.width?.from;
  if (from !== undefined && widthRank < WIDTH_CELL_RANK[from]) {
    return false;
  }
  const below = condition.width?.below;
  if (below !== undefined && widthRank >= WIDTH_CELL_RANK[below]) {
    return false;
  }
  return (
    (condition.pointer === undefined || condition.pointer === pointer) &&
    (condition.contrast === undefined || condition.contrast === contrast) &&
    (condition.motion === undefined || condition.motion === motion)
  );
}

const REACHABLE_MATCH_SET_CACHE = new WeakMap<
  ReadonlyArray<ResolvedThemeAdaptationRule>,
  number[][]
>();

/** Every reachable ordered adaptation-rule match set, including the root. */
function reachableAdaptationMatchSets(
  rules: ReadonlyArray<ResolvedThemeAdaptationRule>,
): number[][] {
  const cached = REACHABLE_MATCH_SET_CACHE.get(rules);
  if (cached !== undefined) {
    return cached;
  }
  const matchSets = new Map<string, number[]>();
  for (let widthRank = 0; widthRank <= 5; widthRank++) {
    for (const pointer of ['coarse', 'fine', 'none'] as const) {
      for (const contrast of [
        'more',
        'less',
        'no-preference',
        'custom',
      ] as const) {
        for (const motion of ['reduce', 'no-preference'] as const) {
          const indexes = rules.flatMap((rule, index) =>
            adaptationConditionMatchesCell(
              rule.when,
              widthRank,
              pointer,
              contrast,
              motion,
            )
              ? [index]
              : [],
          );
          matchSets.set(indexes.join(','), indexes);
        }
      }
    }
  }
  const reachable = [...matchSets.values()];
  REACHABLE_MATCH_SET_CACHE.set(rules, reachable);
  return reachable;
}

function effectiveAdaptationTokenValues(
  rootTokens: Record<string, string>,
  rootLocalTokens: Record<string, string> | undefined,
  rootAliases: ReadonlyArray<readonly [string, string]>,
  rules: ReadonlyArray<ResolvedThemeAdaptationRule>,
  matchingRuleIndexes: ReadonlyArray<number>,
  conditionalAliases: ReadonlyArray<
    ReadonlyArray<readonly [string, string]>
  > = [],
): TokenValues {
  const effective = createTokenCascade(
    rootTokens,
    Object.fromEntries(rootAliases),
    rootLocalTokens,
  );
  for (const index of matchingRuleIndexes) {
    const rule = rules[index];
    assignTokenCascade(
      effective,
      rule.tokens,
      Object.fromEntries(conditionalAliases[index] ?? []),
      rule.localTokens,
    );
  }
  // Emission replays authored roles after every ordinary adaptation block so
  // an explicit role beats aliases from any later overlapping rule.
  for (const index of matchingRuleIndexes) {
    assignTokenCascade(
      effective,
      Object.fromEntries(authoredStatusRoleEntries(rules[index].tokens)),
    );
  }
  return effective.values;
}

function retainedAdaptationRules(
  theme: ThemeRuleSource,
): ResolvedThemeAdaptationRule[] {
  if (!('__adaptations' in theme) && !('__adaptationRules' in theme)) {
    return [];
  }
  return resolvedAdaptationRules(theme as DefinedTheme);
}

/** Root status roles a theme leaves unset: INV17-derived values and INV16 aliases. */
export function generatedScopedStatusRoleDefaults(
  tokens: Record<string, string>,
  localTokens: Record<string, string> = {},
  rules: ReadonlyArray<ResolvedThemeAdaptationRule> = [],
): [string, string][] {
  // INV17: roles a theme leaves unset while setting their status source are
  // computed against the theme's own surfaces first; the aliases below then
  // treat them as present, so icon and border roles follow a derived text role.
  const entries: [string, string][] = deriveStatusRoleTokens(
    tokens,
    localTokens,
  );
  const authoredRoot = createTokenCascade(
    tokens,
    Object.fromEntries(entries),
    localTokens,
  ).values;
  const states = reachableAdaptationMatchSets(rules).map(indexes => ({
    indexes,
    values: effectiveAdaptationTokenValues(
      tokens,
      localTokens,
      entries,
      rules,
      indexes,
    ),
  }));

  for (const [role, source] of SCOPED_REFERENCE_DEFAULTS) {
    const alias = `var(${source})`;
    if (
      authoredRoot[role] !== undefined ||
      (authoredRoot[source] === undefined &&
        !entries.some(([emitted]) => emitted === source))
    ) {
      continue;
    }
    const isSafe = states.every(
      ({values}) =>
        values[role] !== undefined ||
        !tokenValuesWouldHaveCycleWithValue(values, role, alias),
    );
    if (isSafe) {
      entries.push([role, alias]);
      for (const {values} of states) {
        if (values[role] === undefined) {
          values[role] = alias;
        }
      }
    }
  }
  // One canonical order whether a role is derived or aliased, so themes that
  // differ only in which roles needed computing still emit comparable rules.
  return entries.sort(
    ([a], [b]) =>
      (STATUS_ROLE_ORDER.get(a) ?? 0) - (STATUS_ROLE_ORDER.get(b) ?? 0),
  );
}

function authoredStatusRoleEntries(
  tokens: Record<string, string>,
): [string, string][] {
  const canonicalTokens = createTokenCascade(tokens).values;
  return SCOPED_REFERENCE_DEFAULTS.flatMap(([role]) => {
    const value = canonicalTokens[role];
    return value === undefined ? [] : [[role, stringifyTokenValue(value)]];
  });
}

function tokenValueIsAliasOf(value: unknown, source: string): boolean {
  return (
    analyzeDeclarationValue(stringifyTokenValue(value)).singleVarReference ===
    source
  );
}

function mediaRoleRestorationValue(role: string, value: string): string {
  const source = SCOPED_REFERENCE_SOURCES.get(role);
  return source !== undefined && tokenValueIsAliasOf(value, source)
    ? value
    : 'inherit';
}

function generatedAdaptationStatusRoleDefaults(
  rootTokens: Record<string, string>,
  rootLocalTokens: Record<string, string> | undefined,
  rules: ReadonlyArray<ResolvedThemeAdaptationRule>,
  rootAliases: ReadonlyArray<readonly [string, string]>,
): [string, string][][] {
  const aliases = rules.map((): [string, string][] => []);
  const rootValues = createTokenCascade(
    rootTokens,
    Object.fromEntries(rootAliases),
    rootLocalTokens,
  ).values;
  const states = reachableAdaptationMatchSets(rules).map(indexes => ({
    indexes,
    values: effectiveAdaptationTokenValues(
      rootTokens,
      rootLocalTokens,
      rootAliases,
      rules,
      indexes,
      aliases,
    ),
  }));

  for (const [index, rule] of rules.entries()) {
    const authoredRule = createTokenCascade(
      rule.tokens,
      rule.localTokens,
    ).values;
    // INV17 in an adaptation: a rule that changes a colour the derivation
    // measures gets the roles derived from the root and that rule together.
    if (Object.keys(authoredRule).some(token => STATUS_MEASURED.test(token))) {
      const ruleDerived = new Map(
        deriveStatusRoleTokens(
          {...rootTokens, ...rule.tokens},
          {...rootLocalTokens, ...rule.localTokens},
        ),
      );
      for (const [role, value] of ruleDerived) {
        if (authoredRule[role] === undefined && rootValues[role] !== value) {
          aliases[index].push([role, value]);
        }
      }
    }
    // Roles this rule derived count as set: they are not overwritten by an
    // alias, and roles that follow them (icon and border) alias them here.
    const ruleRoles = new Map(aliases[index]);
    const ruleSources = {...authoredRule, ...Object.fromEntries(ruleRoles)};
    for (const [role, source] of SCOPED_REFERENCE_DEFAULTS) {
      const alias = `var(${source})`;
      const rootRole = rootValues[role];
      if (
        ruleRoles.has(role) ||
        authoredRule[role] !== undefined ||
        (ruleSources[source] === undefined &&
          !aliases[index].some(([emitted]) => emitted === source)) ||
        rootRole !== undefined
      ) {
        continue;
      }

      const matchingStates = states.filter(({indexes}) =>
        indexes.includes(index),
      );
      const isSafe = matchingStates.every(
        ({values}) =>
          values[role] !== undefined ||
          !tokenValuesWouldHaveCycleWithValue(values, role, alias),
      );
      if (isSafe) {
        aliases[index].push([role, alias]);
        for (const {values} of matchingStates) {
          if (values[role] === undefined) {
            values[role] = alias;
          }
        }
      }
    }
  }
  return aliases;
}

function generatedMediaStatusRoleDefaults(
  tokens: Record<string, string>,
  rootTokens: Record<string, string>,
  rootLocalTokens: Record<string, string> | undefined,
  rules: ReadonlyArray<ResolvedThemeAdaptationRule>,
  rootAliases: ReadonlyArray<readonly [string, string]>,
): [string, string][] {
  const aliases: [string, string][] = [];
  const rootValues = createTokenCascade(
    rootTokens,
    Object.fromEntries(rootAliases),
    rootLocalTokens,
  ).values;
  // A media surface sits on content the compiler cannot measure, so a status
  // colour set there reaches its roles as an INV16 alias, even where the root
  // holds an INV17-derived value.
  const rootDerived = new Set(
    deriveStatusRoleTokens(rootTokens, rootLocalTokens).map(([role]) => role),
  );
  const authoredMedia = createTokenCascade(tokens).values;
  const authoredRolesByRule = rules.map(
    rule => new Map(authoredStatusRoleEntries(rule.tokens)),
  );
  const states = reachableAdaptationMatchSets(rules).map(indexes => ({
    indexes,
    values: {...authoredMedia},
  }));
  const candidateValueFor = (
    role: string,
    alias: string,
    matchingRuleIndexes: ReadonlyArray<number>,
  ): string => {
    const candidate = createTokenCascade({[role]: alias});
    for (const index of matchingRuleIndexes) {
      const authoredValue = authoredRolesByRule[index].get(role);
      if (authoredValue !== undefined) {
        assignTokenCascade(candidate, {
          [role]: mediaRoleRestorationValue(role, authoredValue),
        });
      }
    }
    return stringifyTokenValue(candidate.values[role]);
  };

  for (const [role, source] of SCOPED_REFERENCE_DEFAULTS) {
    const alias = `var(${source})`;
    const rootRole = rootValues[role];
    if (
      authoredMedia[role] !== undefined ||
      (authoredMedia[source] === undefined &&
        !aliases.some(([emitted]) => emitted === source)) ||
      (rootRole !== undefined &&
        !tokenValueIsAliasOf(rootRole, source) &&
        !rootDerived.has(role))
    ) {
      continue;
    }

    const candidateValues = states.map(({indexes, values}) => ({
      values,
      candidate: candidateValueFor(role, alias, indexes),
    }));
    const isSafe = candidateValues.every(
      ({values, candidate}) =>
        values[role] === candidate ||
        !tokenValuesWouldHaveCycleWithValue(values, role, candidate),
    );
    if (isSafe) {
      aliases.push([role, alias]);
      for (const {values, candidate} of candidateValues) {
        values[role] = candidate;
      }
    }
  }
  // Content on a fill does not depend on the surface beneath it, so a status
  // fill set here gets its INV17 content colour (theme-compilation INV17).
  const mediaFills = new Set(
    STATUS_NAMES.filter(
      status =>
        authoredMedia[`--color-${status}`] !== undefined &&
        authoredMedia[`--color-on-${status}`] === undefined,
    ).map(status => `--color-on-${status}`),
  );
  if (mediaFills.size > 0) {
    for (const [role, value] of deriveStatusRoleTokens(
      {...rootTokens, ...tokens},
      rootLocalTokens,
    )) {
      if (mediaFills.has(role) && rootValues[role] !== value) {
        aliases.push([role, value]);
      }
    }
  }
  return aliases;
}

/** The `:scope` token block for portable and theme-local token values. */
function tokenBlock(
  source: ThemeRuleSource,
  location: string,
  sink: DiagnosticSink,
  tokenEntries: [string, string][] = Object.entries(source.tokens),
): string | null {
  const declarations = [
    // Font sizes follow the reader's text size where the root Theme sets the
    // scales. Elsewhere each scale is 1.
    joinDeclarations(
      readerTextSizeEntries(tokenEntries),
      `${location}tokens`,
      sink,
    ),
    joinDeclarations(
      Object.entries(source.localTokens ?? {}),
      `${location}localTokens`,
      sink,
    ),
  ]
    .filter(block => block.length > 0)
    .join('\n');
  const hasEntries =
    tokenEntries.length > 0 || Object.keys(source.localTokens ?? {}).length > 0;
  return hasEntries ? `  :scope {\n${declarations}\n  }` : null;
}

/** `components.button["variant:secondary"]`-style location for a rule. */
function componentLocation(
  prefix: string,
  component: string,
  key: string,
): string {
  return `${prefix}components.${component}[${JSON.stringify(key)}]`;
}

// =============================================================================
// Public API
// =============================================================================

/**
 * Generate the intermediary CSS rules for a theme.
 *
 * Returns an array of CSS rule strings — the shared format used by both
 * the runtime path (useInsertionEffect) and the build path (astryx theme build).
 */
/**
 * The parts of a theme that turn into CSS rules.
 *
 * Narrower than `DefinedTheme` on purpose: an adaptation rule is not a whole
 * theme, and it calls this with only the values that rule writes. Typing the
 * parameter as `DefinedTheme` would let a future field be read here and silently
 * lost for every conditional rule, with no type error to catch it.
 */
export interface ThemeRuleSource {
  /** Resolved portable token values. */
  tokens: Record<string, string>;
  /** Resolved theme-local token values. */
  localTokens?: Record<string, string>;
  /** Resolved component style overrides. */
  components?: ComponentStyleMap;
}

interface StatusRoleGenerationContext {
  theme: DefinedTheme;
  rules: ResolvedThemeAdaptationRule[];
  rootAliases: [string, string][];
  adaptationAliases?: [string, string][][];
}

interface StatusRoleGenerationCacheEntry {
  signature: string;
  context: StatusRoleGenerationContext;
}

const STATUS_ROLE_GENERATION_CACHE = new WeakMap<
  DefinedTheme,
  StatusRoleGenerationCacheEntry
>();

let activeStatusRoleGeneration: StatusRoleGenerationContext | undefined;

function tokenSetSignature(
  tokens: Record<string, unknown> | undefined,
): (readonly [string, string, string])[] {
  return Object.entries(tokens ?? {}).map(
    ([name, value]): readonly [string, string, string] => [
      name,
      typeof value,
      stringifyTokenValue(value),
    ],
  );
}

function statusRoleGenerationSignature(
  theme: DefinedTheme,
  rules: ReadonlyArray<ResolvedThemeAdaptationRule>,
): string {
  return JSON.stringify([
    tokenSetSignature(theme.tokens),
    tokenSetSignature(theme.localTokens),
    rules.map(rule => [
      rule.query,
      rule.when,
      tokenSetSignature(rule.tokens),
      tokenSetSignature(rule.localTokens),
      rule.components,
    ]),
  ]);
}

function createStatusRoleGenerationContext(
  theme: DefinedTheme,
): StatusRoleGenerationContext {
  const rules = resolvedAdaptationRules(theme);
  const signature = statusRoleGenerationSignature(theme, rules);
  const cached = STATUS_ROLE_GENERATION_CACHE.get(theme);
  if (cached?.signature === signature) {
    return cached.context;
  }
  const context: StatusRoleGenerationContext = {
    theme,
    rules,
    rootAliases: generatedScopedStatusRoleDefaults(
      theme.tokens,
      theme.localTokens,
      rules,
    ),
  };
  STATUS_ROLE_GENERATION_CACHE.set(theme, {signature, context});
  return context;
}

function statusRoleGenerationContext(
  theme: DefinedTheme,
): StatusRoleGenerationContext {
  return activeStatusRoleGeneration?.theme === theme
    ? activeStatusRoleGeneration
    : createStatusRoleGenerationContext(theme);
}

function adaptationStatusRoleDefaults(
  context: StatusRoleGenerationContext,
): [string, string][][] {
  context.adaptationAliases ??= generatedAdaptationStatusRoleDefaults(
    context.theme.tokens,
    context.theme.localTokens,
    context.rules,
    context.rootAliases,
  );
  return context.adaptationAliases;
}

export function generateThemeRules(
  theme: ThemeRuleSource,
  warnings?: string[],
): string[] {
  const parts: string[] = [];
  const sink = diagnosticSink(warnings);

  // Bare prose rules reference semantic variables instead of baking the root
  // value. That lets adaptation token writes take effect through CSS alone
  // without duplicating prose selectors inside every media query.
  const val = (key: string): string => `var(${key})`;

  // 1. Token block — CSS custom properties on :scope. Source-derived status
  // aliases live here once; conditional rules only emit authored writes.
  const context =
    activeStatusRoleGeneration?.theme === theme
      ? activeStatusRoleGeneration
      : undefined;
  const rules = context?.rules ?? retainedAdaptationRules(theme);
  const rootAliases =
    context?.rootAliases ??
    generatedScopedStatusRoleDefaults(theme.tokens, theme.localTokens, rules);
  const tokenRules = tokenBlock(theme, '', sink, [
    ...Object.entries(theme.tokens),
    ...rootAliases,
  ]);
  if (tokenRules !== null) {
    parts.push(tokenRules);
  }

  // 1b. Base font — apply the theme's declared body font to the scope root.
  // Components styled with `font-family: inherit` (SideNav items, Buttons)
  // otherwise resolve against the browser default serif, since nothing else
  // sets a page font. `font-family` inherits, so one rule on :scope covers
  // the tree. Only emitted when the theme declares a body font; a bare theme
  // still contributes no font rule of its own.
  if (theme.tokens['--font-family-body']) {
    parts.push(`  :scope {\n    font-family: var(--font-family-body);\n  }`);
  }

  // 2. Component overrides: stable .astryx-* target classes combined with
  // reflected data-* selectors for visual props and runtime states.
  if (theme.components) {
    generateComponentRules(theme.components, parts, {sink});
  }

  // 3. Prose HTML element rules (h1-h6, p, small, code, hr)
  generateProseRules(val, parts);

  // 4. Prop-level color overrides (for text/heading/link specificity)
  generateColorOverrides(theme.components || {}, parts);

  // 5. Text `size`-prop font-size overrides (so an explicit size beats a
  //    themed type's font-size across the astryx-base → astryx-theme layers)
  generateSizeOverrides(theme.components || {}, parts);

  // 6. Heading `weight`-prop overrides. These are emitted after authored type
  //    rules in the same layer so an explicit prop remains an override even
  //    when a custom visual type declares its own default weight.
  generateHeadingWeightOverrides(theme.components || {}, parts);

  // (on-media rules are generated separately — see generateOnMediaCSS)

  return parts;
}

/** Named Heading/Text weight props and their theme-owned token values. */
const HEADING_WEIGHT_TOKEN_MAP: Record<string, string> = {
  normal: 'var(--font-weight-normal)',
  medium: 'var(--font-weight-medium)',
  semibold: 'var(--font-weight-semibold)',
  bold: 'var(--font-weight-bold)',
};

interface HeadingWeightOverrideOptions {
  /** Scope selectors to one on-media surface. */
  surface?: MediaSurface;
  /** Effective root components used as the surface fallback. */
  inheritedComponents?: Record<string, unknown>;
  /** Emit all standard choices even when this component map has no Heading. */
  forceAll?: boolean;
  /** Emit only choices whose rule explicitly writes fontWeight. */
  authoredOnly?: boolean;
}

/**
 * Re-emit Heading's explicit weight choices in the theme layer.
 *
 * Component and type overrides live above the StyleX base layer, so the
 * component's ordinary weight class cannot win there by itself. Emitting the
 * reflected weight classes after authored component rules makes the public
 * `weight` prop a dependable override of a type or level default.
 */
function generateHeadingWeightOverrides(
  components: Record<string, unknown>,
  parts: string[],
  {
    surface,
    inheritedComponents,
    forceAll = false,
    authoredOnly = false,
  }: HeadingWeightOverrideOptions = {},
): void {
  const headingRules = components.heading;
  const headingRuleMap =
    headingRules &&
    typeof headingRules === 'object' &&
    !Array.isArray(headingRules)
      ? (headingRules as Record<string, unknown>)
      : undefined;
  if (!headingRuleMap && !forceAll) {
    return;
  }
  const inheritedHeadingRules = inheritedComponents?.heading;
  const inheritedHeadingRuleMap =
    inheritedHeadingRules && typeof inheritedHeadingRules === 'object'
      ? (inheritedHeadingRules as Record<string, unknown>)
      : undefined;

  for (const [weightName, weightValue] of Object.entries(
    HEADING_WEIGHT_TOKEN_MAP,
  )) {
    const styleKey = `weight:${weightName}`;
    const authoredWeight = headingRuleMap
      ? getAuthoredHeadingWeight(headingRuleMap, styleKey)
      : undefined;
    if (authoredOnly && authoredWeight === undefined) {
      continue;
    }
    const inheritedWeight = inheritedHeadingRuleMap
      ? getAuthoredHeadingWeight(inheritedHeadingRuleMap, styleKey)
      : undefined;
    const effectiveWeight = authoredWeight ?? inheritedWeight ?? weightValue;
    const suffix = parseStyleKey(styleKey);
    const selector = componentSelector('heading', suffix, surface);
    parts.push(`  ${selector} { font-weight: ${effectiveWeight}; }`);
  }
}

/**
 * The `fontWeight` a heading rule authors for `styleKey`, or undefined when
 * it has none. A value that cannot stay one declaration is treated as not
 * authored, so the override falls back to the inherited or token weight
 * instead of interpolating it; the drop itself is reported where that same
 * rule's declarations are emitted, so it is not reported twice here.
 */
function getAuthoredHeadingWeight(
  headingRuleMap: Record<string, unknown>,
  styleKey: string,
): string | undefined {
  const rule = headingRuleMap[styleKey];
  if (rule == null || typeof rule !== 'object' || Array.isArray(rule)) {
    return undefined;
  }
  const fontWeight = (rule as Record<string, unknown>).fontWeight;
  return typeof fontWeight === 'string' &&
    checkDeclarationValue(fontWeight) === null
    ? fontWeight
    : undefined;
}

/** Options shared by root, adaptation, and media-surface component lowering. */
interface ComponentRuleOptions {
  resetInheritedPaddingSpecificity?: boolean;
  surface?: MediaSurface;
  /** Receives dropped declarations; defaults to `console.warn`. */
  sink?: DiagnosticSink;
  /** Location prefix for diagnostics, e.g. `onDark.` or `adaptations[0].`. */
  location?: string;
}

/**
 * Generate component override rules using stable `.astryx-*` target classes
 * and reflected `data-*` selectors for prop/state keys. Handles derived var
 * expansion and container padding mapping for every theme layer.
 */
function generateComponentRules(
  components: Record<
    string,
    Record<string, Record<string, string | Record<string, string>>>
  >,
  parts: string[],
  {
    resetInheritedPaddingSpecificity = false,
    surface,
    sink = warnToConsole,
    location: locationPrefix = '',
  }: ComponentRuleOptions = {},
): void {
  for (const [component, rules] of Object.entries(components)) {
    for (const [key, styles] of Object.entries(rules)) {
      const entries = Object.entries(styles);
      if (entries.length === 0) {
        continue;
      }

      const suffix = parseStyleKey(key);
      const baseSelector = componentSelector(component, suffix, surface);
      const location = componentLocation(locationPrefix, component, key);

      // Separate regular properties from pseudo-class overrides
      const props: [string, string][] = [];
      const pseudos: [string, Record<string, string>][] = [];

      for (const [prop, value] of entries) {
        if (prop.startsWith(':') && typeof value === 'object') {
          pseudos.push([prop, value]);
        } else if (
          acceptDeclaration(
            toKebabCase(prop),
            `${value as string}`,
            location,
            sink,
          )
        ) {
          props.push([prop, value as string]);
        }
      }

      // Derived var expansion: for each CSS property, check if the
      // component has derived var entries and emit additional declarations.
      // Entries are processed in order (priority).
      // - `vars`: emit internal CSS custom property declarations
      // - `expand: 'container'`: expand padding to container layout tokens
      // - `replaces: true`: emit only the var, dropping the source property
      let finalProps = props;
      const derivedProps: [string, string][] = [];
      let containerExpanded = false;
      const replacedProps = new Set<string>();

      for (const [prop, value] of props) {
        const derived = getDerivedVars(component, prop);
        // Padding longhands (paddingBlock, paddingInline, etc.) also
        // match the 'padding' derived entry for container expansion.
        const paddingDerived =
          PADDING_PROPS.has(prop) && prop !== 'padding'
            ? getDerivedVars(component, 'padding')
            : [];
        for (const entry of [...derived, ...paddingDerived]) {
          if (entry.expand === 'container' && PADDING_PROPS.has(prop)) {
            containerExpanded = true;
          }
          if (entry.replaces) {
            replacedProps.add(prop);
          }
          if (entry.vars) {
            for (const varName of entry.vars) {
              derivedProps.push([varName, value]);
            }
          }
        }
        // A physical block longhand reaches the container expansion only. It
        // names one edge, so it must not feed a `vars` entry above, which
        // carries the padding for the whole box.
        if (
          prop in PHYSICAL_BLOCK_PADDING_PROPS &&
          getDerivedVars(component, 'padding').some(
            e => e.expand === 'container',
          )
        ) {
          containerExpanded = true;
        }
      }

      // Container padding expansion: replace padding props with
      // component-scoped container tokens for layout integration.
      if (containerExpanded) {
        const paddingProps = props.filter(([p]) =>
          CONTAINER_PADDING_PROPS.has(p),
        );
        const nonPaddingProps = props.filter(
          ([p]) => !CONTAINER_PADDING_PROPS.has(p),
        );
        const parsed = parsePadding(paddingProps);
        const containerTokens = expandContainerPadding(
          component,
          parsed,
          resetInheritedPaddingSpecificity,
        );
        finalProps = [...nonPaddingProps, ...containerTokens];
      }

      // Drop properties whose derived entry set `replaces` — their value is
      // carried by the emitted var and must not land on the class element.
      if (replacedProps.size > 0) {
        finalProps = finalProps.filter(([p]) => !replacedProps.has(p));
      }

      if (derivedProps.length > 0) {
        finalProps = [...finalProps, ...derivedProps];
      }

      // Emit base rule
      if (finalProps.length > 0) {
        const declarations = joinDeclarations(
          finalProps,
          location,
          sink,
          toKebabCase,
        );
        parts.push(`  ${baseSelector} {\n${declarations}\n  }`);
      }

      // Emit pseudo-class rules
      for (const [pseudo, pseudoStyles] of pseudos) {
        const pseudoEntries = Object.entries(pseudoStyles);
        if (pseudoEntries.length > 0) {
          const declarations = joinDeclarations(
            pseudoEntries,
            `${location}[${JSON.stringify(pseudo)}]`,
            sink,
            toKebabCase,
          );
          parts.push(...pseudoRules(baseSelector, pseudo, declarations));
        }
      }
    }
  }
}

/**
 * Generate prose HTML element default rules (h1-h6, p, small, code, hr).
 * Wrapped in :where() for zero specificity — these are defaults that
 * any class-based style (StyleX, .astryx-* overrides) should beat.
 * The caller places these in the reset layer (not astryx-theme) so they
 * sit below all component styles in the cascade.
 */
function generateProseRules(
  val: (key: string) => string,
  parts: string[],
): void {
  parts.push(`  :where(h1, h2, h3, h4, h5, h6) {
    font-family: var(--font-family-heading);
    color: var(--color-text-primary);
  }`);

  for (let level = 1; level <= 6; level++) {
    parts.push(`  :where(h${level}) {
    font-size: ${val(`--text-heading-${level}-size`)};
    font-weight: ${val(`--text-heading-${level}-weight`)};
    line-height: ${val(`--text-heading-${level}-leading`)};
  }`);
  }

  parts.push(`  :where(p) {
    font-family: var(--font-family-body);
    font-size: ${val('--text-body-size')};
    font-weight: ${val('--text-body-weight')};
    line-height: ${val('--text-body-leading')};
    color: var(--color-text-primary);
  }`);

  parts.push(`  :where(small) {
    font-size: ${val('--text-supporting-size')};
    font-weight: ${val('--text-supporting-weight')};
    line-height: ${val('--text-supporting-leading')};
    color: var(--color-text-secondary);
  }`);

  parts.push(`  :where(code, pre) {
    font-family: var(--font-family-code);
    font-size: ${val('--text-code-size')};
    line-height: ${val('--text-code-leading')};
  }`);

  parts.push(`  :where(hr) {
    border: none;
    border-top: 1px solid var(--color-border);
  }`);
}

/**
 * Generate prop-level color override rules for text/heading/link components.
 * These ensure color prop classes override theme token changes.
 */
function generateColorOverrides(
  components: Record<string, unknown>,
  parts: string[],
  surface?: MediaSurface,
): void {
  const TEXT_COLOR_MAP: Record<string, string> = {
    primary: 'var(--color-text-primary)',
    secondary: 'var(--color-text-secondary)',
    disabled: 'var(--color-text-disabled)',
    placeholder: 'var(--color-text-secondary)',
    accent: 'var(--color-text-accent)',
    // A label that follows its owner's color, such as a Link's, keeps doing
    // so when a theme styles the target's base color.
    inherit: 'inherit',
  };

  const touchesText = 'text' in components;
  const touchesHeading = 'heading' in components;
  const touchesLink = 'link' in components;

  if (touchesText || touchesHeading || touchesLink) {
    for (const [colorName, colorValue] of Object.entries(TEXT_COLOR_MAP)) {
      if (touchesText) {
        parts.push(
          `  ${componentSelector('text', parseStyleKey(`color:${colorName}`), surface)} { color: ${colorValue}; }`,
        );
      }
      if (touchesHeading) {
        parts.push(
          `  ${componentSelector('heading', parseStyleKey(`color:${colorName}`), surface)} { color: ${colorValue}; }`,
        );
      }
      if (touchesLink) {
        parts.push(
          `  ${componentSelector('link', parseStyleKey(`color:${colorName}`), surface)} { color: ${colorValue}; }`,
        );
      }
    }
  }
}

/**
 * Map a Text `size` prop value to its raw font-size token.
 * Mirrors `sizeStyles` in `Text/text.stylex.ts` (note `xsm` → `--font-size-xs`).
 * <!-- SYNC: packages/core/src/Text/text.stylex.ts (sizeStyles) -->
 */
const TEXT_SIZE_TOKEN_MAP: Record<string, string> = {
  '4xs': 'var(--font-size-4xs)',
  '3xs': 'var(--font-size-3xs)',
  '2xs': 'var(--font-size-2xs)',
  xsm: 'var(--font-size-xs)',
  sm: 'var(--font-size-sm)',
  base: 'var(--font-size-base)',
  lg: 'var(--font-size-lg)',
  xl: 'var(--font-size-xl)',
  '2xl': 'var(--font-size-2xl)',
  '3xl': 'var(--font-size-3xl)',
  '4xl': 'var(--font-size-4xl)',
};

/**
 * Generate `size`-prop font-size overrides for the Text component.
 *
 * The `size` prop is documented as a font-size override that wins over the
 * size implied by `type`. Its StyleX class lives in `@layer astryx-base`, but a
 * theme's per-type font-size rule (`.astryx-text.<type>`) lives in the higher
 * `@layer astryx-theme`, so the layer cascade let the theme silently shadow
 * `size` for any `type` the theme styled. Re-emitting the size classes here —
 * same layer as the type rules, same `.astryx-text.<x>` specificity, later in
 * source — restores `size` as a real override.
 *
 * Only `font-size` is overridden; line-height and other type properties are
 * intentionally preserved, matching the prop's documented contract.
 *
 * Gated on the theme touching `text` (which includes the auto-generated
 * type-scale rules) — with no theme type rule to beat, the base-layer StyleX
 * class already wins and no override is needed.
 */
function generateSizeOverrides(
  components: Record<string, unknown>,
  parts: string[],
  surface?: MediaSurface,
): void {
  if (!('text' in components)) {
    return;
  }
  for (const [sizeName, sizeValue] of Object.entries(TEXT_SIZE_TOKEN_MAP)) {
    const suffix = parseStyleKey(`size:${sizeName}`);
    parts.push(
      `  ${componentSelector('text', suffix, surface)} { font-size: ${sizeValue}; }`,
    );
  }
}

/**
 * Generate theme rules split into component and prose groups.
 *
 * Prose element rules (h1-h6, p, small, code, hr) style bare HTML elements
 * as themed defaults — conceptually the same tier as the CSS reset. They
 * belong in the reset layer so any class-based style wins.
 *
 * Component rules (tokens, stable .astryx-* targets plus data-* selectors) are
 * that need to beat StyleX — they stay in astryx-theme (above StyleX layers).
 */
export function generateThemeRulesSplit(
  theme: DefinedTheme,
  warnings?: string[],
): ThemeRulesSplit {
  const allRules = generateThemeRules(theme, warnings);

  const prose: string[] = [];
  const component: string[] = [];

  for (const rule of allRules) {
    if (rule.trimStart().startsWith(':where(')) {
      prose.push(rule);
    } else {
      component.push(rule);
    }
  }

  return {component, prose};
}

function resolvedAdaptationRules(
  theme: DefinedTheme,
): ResolvedThemeAdaptationRule[] {
  // Retained metadata is part of the built-theme contract. Validate it even
  // when a concrete rule cache is present so a stale or malformed breakpoint
  // map cannot bypass the same checks live themes receive.
  const normalized =
    theme.__adaptations === undefined
      ? undefined
      : normalizeThemeAdaptations(theme.name, theme.__adaptations, undefined);
  if (Array.isArray(theme.__adaptationRules)) {
    return theme.__adaptationRules;
  }
  if (normalized === undefined) {
    return [];
  }
  return (
    resolveThemeAdaptationRules(
      theme.name,
      normalized,
      theme.__axes ?? {},
      theme.tokens,
      theme.localTokens,
      theme.components,
    ) ?? []
  );
}

/**
 * Generate CSS for on-media token and component overrides.
 *
 * Emitted in an unbounded @scope (no `to` limit) so the rules can reach
 * [data-astryx-media] elements. Parent theme component overrides flow through
 * to media contexts — only tokens change. Themes can further customize
 * via onDark.components / onLight.components.
 */
export function generateOnMediaCSS(
  theme: DefinedTheme,
  warnings?: string[],
): string {
  const parts: string[] = [];
  const scopeSelector = themeScopeStart(theme.name);
  const sink = diagnosticSink(warnings);
  const context = statusRoleGenerationContext(theme);
  const {rules, rootAliases} = context;
  const mediaStatusRoleDefaults = new Map<
    'dark' | 'light',
    [string, string][]
  >();

  for (const surface of ['dark', 'light'] as const) {
    const onMedia = surface === 'dark' ? theme.__onDark : theme.__onLight;
    if (!onMedia) {
      continue;
    }
    const location = surface === 'dark' ? 'onDark.' : 'onLight.';

    // Token overrides. MediaTheme writes on a descendant surface, so a source
    // alias must be local unless an authored root/adaptation role owns it.
    const statusRoleDefaults = generatedMediaStatusRoleDefaults(
      onMedia.tokens,
      theme.tokens,
      theme.localTokens,
      rules,
      rootAliases,
    );
    mediaStatusRoleDefaults.set(surface, statusRoleDefaults);
    const tokenEntries = [
      ...Object.entries(onMedia.tokens),
      ...statusRoleDefaults,
    ];
    if (tokenEntries.length > 0) {
      // The surface re-declares font sizes the way a theme's root does, so they
      // keep following the reader's text size there (see dynamicType.ts).
      const declarations = joinDeclarations(
        readerTextSizeEntries(tokenEntries),
        `${location}tokens`,
        sink,
      );
      parts.push(`  ${mediaSelector(surface)} {\n${declarations}\n  }`);
    }

    // Component overrides use the same lowering as root and adaptations so a
    // surface writes the same derived leaf and can win by source order.
    if (onMedia.components) {
      generateComponentRules(onMedia.components, parts, {
        resetInheritedPaddingSpecificity: true,
        surface,
        sink,
        location,
      });
      generateColorOverrides(onMedia.components, parts, surface);
      generateSizeOverrides(onMedia.components, parts, surface);

      // Apply the effective explicit Heading weight after media-specific type
      // rules. A surface-authored target wins, followed by the inherited main
      // target and then the built-in token fallback.
      generateHeadingWeightOverrides(onMedia.components, parts, {
        surface,
        inheritedComponents: theme.components,
      });
    }
  }

  const adaptationMediaRoleBlocks: string[] = [];
  for (const [index, rule] of rules.entries()) {
    const authoredRoles = authoredStatusRoleEntries(rule.tokens);
    if (authoredRoles.length === 0) {
      continue;
    }
    const roleParts: string[] = [];
    for (const surface of ['dark', 'light'] as const) {
      const onMedia = surface === 'dark' ? theme.__onDark : theme.__onLight;
      if (!onMedia) {
        continue;
      }
      const generatedRoles = new Set(
        (mediaStatusRoleDefaults.get(surface) ?? []).map(([role]) => role),
      );
      const restorationEntries: [string, string][] = authoredRoles
        .filter(([role]) => generatedRoles.has(role))
        .map(([role, value]) => [role, mediaRoleRestorationValue(role, value)]);
      if (restorationEntries.length === 0) {
        continue;
      }
      const declarations = joinDeclarations(
        restorationEntries,
        `adaptations[${index}].on${surface}.statusRoles.`,
        sink,
      );
      roleParts.push(`  ${mediaSelector(surface)} {\n${declarations}\n  }`);
    }
    if (roleParts.length > 0) {
      adaptationMediaRoleBlocks.push(
        generateAdaptationMediaBlock(rule.query, roleParts, scopeSelector),
      );
    }
  }

  if (parts.length === 0 && adaptationMediaRoleBlocks.length === 0) {
    return '';
  }

  const blocks: string[] = [];
  if (parts.length > 0) {
    const inner = parts.join('\n\n');
    blocks.push(
      `@scope (${scopeSelector}) to (${THEME_SCOPE_TO}) {\n${inner}\n}`,
    );
  }
  blocks.push(...adaptationMediaRoleBlocks);
  return blocks.join('\n\n');
}

/** Generate only the declarations one adaptation rule writes. */
function generateAdaptationRuleRules(
  rule: ThemeRuleSource,
  location: string,
  sink: DiagnosticSink,
  statusRoleDefaults: [string, string][],
): string[] {
  const parts: string[] = [];
  const tokens = tokenBlock(rule, location, sink, [
    ...Object.entries(rule.tokens),
    ...statusRoleDefaults,
  ]);
  if (tokens !== null) {
    parts.push(tokens);
  }

  if (rule.components) {
    generateComponentRules(rule.components, parts, {
      resetInheritedPaddingSpecificity: true,
      sink,
      location,
    });
    generateColorOverrides(rule.components, parts);
    generateSizeOverrides(rule.components, parts);
  }
  return parts;
}

function hasHeadingComponentRules(
  components: Record<string, unknown> | undefined,
): boolean {
  const headingRules = components?.heading;
  return (
    headingRules !== null &&
    typeof headingRules === 'object' &&
    !Array.isArray(headingRules)
  );
}

function generateAdaptationMediaBlock(
  query: string,
  parts: string[],
  scopeSelector: string,
): string {
  return `@media ${query} {\n  @scope (${scopeSelector}) to (${THEME_SCOPE_TO}) {\n${parts
    .map(indentRule)
    .join('\n\n')}\n  }\n}`;
}

/**
 * Generate CSS for a theme's ordered adaptation rules.
 *
 * Each authored rule stays a separate media block in declaration order. Blocks
 * are never merged, reordered, or value-diffed: a later rule that deliberately
 * writes a root value must remain present so it can override an earlier matching
 * rule. Bare prose follows semantic variables, so token writes need no duplicate
 * prose selectors here.
 */
export function generateAdaptationCSS(
  theme: DefinedTheme,
  warnings?: string[],
): ThemeCSSOutput {
  const sink = diagnosticSink(warnings);
  // Built themes can reach this compiler without passing through defineTheme.
  // Resolve retained metadata so width points remain observable through
  // AppShell and inheritance even when a rule emits no CSS.
  const context = statusRoleGenerationContext(theme);
  const {rules} = context;
  if (rules.length === 0) {
    return {prose: '', component: ''};
  }

  const scopeSelector = themeScopeStart(theme.name);
  const blocks: string[] = [];
  const adaptsHeading = rules.some(rule =>
    hasHeadingComponentRules(rule.components),
  );

  const statusRoleDefaults = adaptationStatusRoleDefaults(context);

  // Emit ordinary rule writes first, without inherited Heading weight
  // fallbacks. Carrying an earlier weight into a later block makes that value
  // active whenever the later condition matches, even if the earlier condition
  // does not. Pairwise merging cannot repair that: multiple mutually exclusive
  // earlier rules can each overlap one broad later rule.
  for (const [index, rule] of rules.entries()) {
    const parts = generateAdaptationRuleRules(
      rule,
      `adaptations[${index}].`,
      sink,
      statusRoleDefaults[index],
    );
    if (parts.length === 0) {
      continue;
    }
    blocks.push(generateAdaptationMediaBlock(rule.query, parts, scopeSelector));
  }

  // Replay explicit role writes after every generated source alias. This keeps
  // an authored role authoritative when its condition overlaps a later rule
  // that changes only the role's source, while the alias still works when the
  // authored-role condition is inactive.
  for (const [index, rule] of rules.entries()) {
    const roleEntries = authoredStatusRoleEntries(rule.tokens);
    if (roleEntries.length === 0) {
      continue;
    }
    const roleRule = tokenBlock(
      {tokens: {}},
      `adaptations[${index}].statusRoles.`,
      sink,
      roleEntries,
    );
    if (roleRule !== null) {
      blocks.push(
        generateAdaptationMediaBlock(rule.query, [roleRule], scopeSelector),
      );
    }
  }

  if (adaptsHeading) {
    // Put one unconditional effective-root guard after every ordinary
    // adaptation block. It restores the public weight prop above every
    // conditional type/level default without attributing any prior rule's
    // value to a condition that did not author it.
    const rootWeightParts: string[] = [];
    generateHeadingWeightOverrides(theme.components ?? {}, rootWeightParts, {
      forceAll: true,
    });
    blocks.push(
      `@scope (${scopeSelector}) to (${THEME_SCOPE_TO}) {\n${rootWeightParts.join(
        '\n\n',
      )}\n}`,
    );

    // Reapply only explicitly authored conditional weight writes, preserving
    // authored rule order so co-matching writes retain last-write-wins.
    for (const rule of rules) {
      const authoredWeightParts: string[] = [];
      generateHeadingWeightOverrides(
        rule.components ?? {},
        authoredWeightParts,
        {authoredOnly: true},
      );
      if (authoredWeightParts.length > 0) {
        blocks.push(
          generateAdaptationMediaBlock(
            rule.query,
            authoredWeightParts,
            scopeSelector,
          ),
        );
      }
    }
  }

  return {prose: '', component: blocks.join('\n\n')};
}

/** Indent the rule start without rewriting newlines inside authored values. */
function indentRule(rule: string): string {
  return `  ${rule}`;
}

/**
 * Generate layered CSS for a theme — runtime path.
 *
 * Returns two CSS blocks for injection into different layers:
 * - `prose`: @scope'd element defaults → inject into @layer reset
 * - `component`: @scope'd token + .astryx-* overrides → inject into @layer astryx-theme
 *
 * This separation ensures prose defaults (what bare HTML looks like in a theme)
 * sit at reset-layer priority where any class-based style wins, while component
 * overrides sit above StyleX so themes can restyle components intentionally.
 *
 * Data-token defaults are owned by the public StyleX `dataVars` group. This
 * generator emits only a theme's explicitly authored token overrides.
 */
export function generateThemeCSS(
  theme: DefinedTheme,
  warnings?: string[],
): ThemeCSSOutput {
  if (activeStatusRoleGeneration?.theme === theme) {
    return generateThemeCSSWithContext(theme, warnings);
  }
  const previous = activeStatusRoleGeneration;
  activeStatusRoleGeneration = createStatusRoleGenerationContext(theme);
  try {
    return generateThemeCSSWithContext(theme, warnings);
  } finally {
    activeStatusRoleGeneration = previous;
  }
}

function generateThemeCSSWithContext(
  theme: DefinedTheme,
  warnings?: string[],
): ThemeCSSOutput {
  const {component, prose} = generateThemeRulesSplit(theme, warnings);
  const scopeSelector = themeScopeStart(theme.name);
  const scopeTo = THEME_SCOPE_TO;

  let proseCss = '';
  if (prose.length > 0) {
    const proseInner = prose.join('\n\n');
    proseCss = `@scope (${scopeSelector}) to (${scopeTo}) {\n${proseInner}\n}`;
  }

  // Component rules: bounded scope (stops at nested themes) +
  // on-media rules in unbounded scope (can reach [data-astryx-media] elements)
  let componentCss = '';
  if (component.length > 0) {
    const componentInner = component.join('\n\n');
    componentCss = `@scope (${scopeSelector}) to (${scopeTo}) {\n${componentInner}\n}`;
  }

  // Adaptations follow the root theme in authored order. Media-surface rules
  // follow adaptations so onDark/onLight keep their specified precedence.
  const adaptationCss = generateAdaptationCSS(theme, warnings);
  if (adaptationCss.component) {
    componentCss = componentCss
      ? `${componentCss}\n\n${adaptationCss.component}`
      : adaptationCss.component;
  }

  const onMediaCss = generateOnMediaCSS(theme, warnings);
  if (onMediaCss) {
    componentCss = componentCss
      ? `${componentCss}\n\n${onMediaCss}`
      : onMediaCss;
  }

  return {prose: proseCss, component: componentCss};
}