@astryxdesign/core 0.6.2 → 0.6.3-canary.039a67e

package/src/theme/generateThemeRules.ts

@@ -6,14 +6,22 @@
  * Shared logic for generating CSS rules from a resolved theme definition,
  * including 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)
- * @output CSS rule strings, split by layer (component vs prose)
+ * @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
  */
 
@@ -26,6 +34,10 @@ import {parseStyleKey} from '../utils/parseStyleKey';
 import {getDerivedVars} from './derivedVarRegistry';
 import {dataTokenDefaults} from './domainTokens/dataTokens';
 import {cssVar, classPrefix, dataAttrNamespace} from '../naming';
+import {
+  checkDeclarationName,
+  checkDeclarationValue,
+} from './declarationBoundary';
 
 /**
  * Theme @scope selectors.
@@ -366,6 +378,117 @@ function expandContainerPadding(
   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 = `${rawValue}`;
+    const prop = mapProp(rawProp);
+    if (acceptDeclaration(prop, value, location, sink)) {
+      lines.push(`    ${prop}: ${value};`);
+    }
+  }
+  return lines.join('\n');
+}
+
+/** The `:scope` token block for portable and theme-local token values. */
+function tokenBlock(
+  source: ThemeRuleSource,
+  location: string,
+  sink: DiagnosticSink,
+): string | null {
+  const declarations = [
+    joinDeclarations(Object.entries(source.tokens), `${location}tokens`, sink),
+    joinDeclarations(
+      Object.entries(source.localTokens ?? {}),
+      `${location}localTokens`,
+      sink,
+    ),
+  ]
+    .filter(block => block.length > 0)
+    .join('\n');
+  const hasEntries =
+    Object.keys(source.tokens).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
 // =============================================================================
@@ -393,9 +516,12 @@ export interface ThemeRuleSource {
   components?: ComponentStyleMap;
 }
 
-export function generateThemeRules(theme: ThemeRuleSource): string[] {
+export function generateThemeRules(
+  theme: ThemeRuleSource,
+  warnings?: string[],
+): string[] {
   const parts: string[] = [];
-  const tokens = theme.tokens;
+  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
@@ -403,21 +529,25 @@ export function generateThemeRules(theme: ThemeRuleSource): string[] {
   const val = (key: string): string => `var(${key})`;
 
   // 1. Token block — CSS custom properties on :scope
-  const tokenEntries = [
-    ...Object.entries(tokens),
-    ...Object.entries(theme.localTokens ?? {}),
-  ];
-  if (tokenEntries.length > 0) {
-    const declarations = tokenEntries
-      .map(([prop, value]) => `    ${prop}: ${value};`)
-      .join('\n');
-    parts.push(`  :scope {\n${declarations}\n  }`);
+  const tokenRules = tokenBlock(theme, '', sink);
+  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, so a bare
+  // theme still contributes no scope rules 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);
+    generateComponentRules(theme.components, parts, {sink});
   }
 
   // 3. Prose HTML element rules (h1-h6, p, small, code, hr)
@@ -513,6 +643,13 @@ function generateHeadingWeightOverrides(
   }
 }
 
+/**
+ * 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,
@@ -522,13 +659,20 @@ function getAuthoredHeadingWeight(
     return undefined;
   }
   const fontWeight = (rule as Record<string, unknown>).fontWeight;
-  return typeof fontWeight === 'string' ? fontWeight : undefined;
+  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;
 }
 
 /**
@@ -545,6 +689,8 @@ function generateComponentRules(
   {
     resetInheritedPaddingSpecificity = false,
     surface,
+    sink = warnToConsole,
+    location: locationPrefix = '',
   }: ComponentRuleOptions = {},
 ): void {
   for (const [component, rules] of Object.entries(components)) {
@@ -556,6 +702,7 @@ function generateComponentRules(
 
       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][] = [];
@@ -564,7 +711,14 @@ function generateComponentRules(
       for (const [prop, value] of entries) {
         if (prop.startsWith(':') && typeof value === 'object') {
           pseudos.push([prop, value]);
-        } else {
+        } else if (
+          acceptDeclaration(
+            toKebabCase(prop),
+            `${value as string}`,
+            location,
+            sink,
+          )
+        ) {
           props.push([prop, value as string]);
         }
       }
@@ -644,9 +798,12 @@ function generateComponentRules(
 
       // Emit base rule
       if (finalProps.length > 0) {
-        const declarations = finalProps
-          .map(([prop, value]) => `    ${toKebabCase(prop)}: ${value};`)
-          .join('\n');
+        const declarations = joinDeclarations(
+          finalProps,
+          location,
+          sink,
+          toKebabCase,
+        );
         parts.push(`  ${baseSelector} {\n${declarations}\n  }`);
       }
 
@@ -654,9 +811,12 @@ function generateComponentRules(
       for (const [pseudo, pseudoStyles] of pseudos) {
         const pseudoEntries = Object.entries(pseudoStyles);
         if (pseudoEntries.length > 0) {
-          const declarations = pseudoEntries
-            .map(([prop, value]) => `    ${toKebabCase(prop)}: ${value};`)
-            .join('\n');
+          const declarations = joinDeclarations(
+            pseudoEntries,
+            `${location}[${JSON.stringify(pseudo)}]`,
+            sink,
+            toKebabCase,
+          );
           parts.push(
             `  ${appendPseudoToSelectorList(baseSelector, pseudo)} {\n${declarations}\n  }`,
           );
@@ -822,8 +982,11 @@ function generateSizeOverrides(
  * 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): ThemeRulesSplit {
-  const allRules = generateThemeRules(theme);
+export function generateThemeRulesSplit(
+  theme: DefinedTheme,
+  warnings?: string[],
+): ThemeRulesSplit {
+  const allRules = generateThemeRules(theme, warnings);
 
   const prose: string[] = [];
   const component: string[] = [];
@@ -847,22 +1010,29 @@ export function generateThemeRulesSplit(theme: DefinedTheme): ThemeRulesSplit {
  * to media contexts — only tokens change. Themes can further customize
  * via onDark.components / onLight.components.
  */
-export function generateOnMediaCSS(theme: DefinedTheme): string {
+export function generateOnMediaCSS(
+  theme: DefinedTheme,
+  warnings?: string[],
+): string {
   const parts: string[] = [];
   const scopeSelector = themeScopeStart(theme.name);
+  const sink = diagnosticSink(warnings);
 
   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
     const tokenEntries = Object.entries(onMedia.tokens);
     if (tokenEntries.length > 0) {
-      const declarations = tokenEntries
-        .map(([prop, value]) => `    ${prop}: ${value};`)
-        .join('\n');
+      const declarations = joinDeclarations(
+        tokenEntries,
+        `${location}tokens`,
+        sink,
+      );
       parts.push(`  ${mediaSelector(surface)} {\n${declarations}\n  }`);
     }
 
@@ -872,6 +1042,8 @@ export function generateOnMediaCSS(theme: DefinedTheme): string {
       generateComponentRules(onMedia.components, parts, {
         resetInheritedPaddingSpecificity: true,
         surface,
+        sink,
+        location,
       });
       generateColorOverrides(onMedia.components, parts, surface);
       generateSizeOverrides(onMedia.components, parts, surface);
@@ -895,22 +1067,22 @@ export function generateOnMediaCSS(theme: DefinedTheme): string {
 }
 
 /** Generate only the declarations one adaptation rule writes. */
-function generateAdaptationRuleRules(rule: ThemeRuleSource): string[] {
+function generateAdaptationRuleRules(
+  rule: ThemeRuleSource,
+  location: string,
+  sink: DiagnosticSink,
+): string[] {
   const parts: string[] = [];
-  const tokenEntries = [
-    ...Object.entries(rule.tokens),
-    ...Object.entries(rule.localTokens ?? {}),
-  ];
-  if (tokenEntries.length > 0) {
-    const declarations = tokenEntries
-      .map(([prop, value]) => `    ${prop}: ${value};`)
-      .join('\n');
-    parts.push(`  :scope {\n${declarations}\n  }`);
+  const tokens = tokenBlock(rule, location, sink);
+  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);
@@ -948,7 +1120,11 @@ function generateAdaptationMediaBlock(
  * rule. Bare prose follows semantic variables, so token writes need no duplicate
  * prose selectors here.
  */
-export function generateAdaptationCSS(theme: DefinedTheme): ThemeCSSOutput {
+export function generateAdaptationCSS(
+  theme: DefinedTheme,
+  warnings?: string[],
+): ThemeCSSOutput {
+  const sink = diagnosticSink(warnings);
   // Built themes can reach this compiler without passing through defineTheme.
   // Validate retained metadata even when it has no rules (and therefore emits
   // no CSS): width points remain observable through AppShell and inheritance.
@@ -965,6 +1141,7 @@ export function generateAdaptationCSS(theme: DefinedTheme): ThemeCSSOutput {
           theme.__axes ?? {},
           theme.tokens,
           theme.localTokens,
+          theme.components,
         )
       : undefined);
   if (!rules || rules.length === 0) {
@@ -982,8 +1159,12 @@ export function generateAdaptationCSS(theme: DefinedTheme): ThemeCSSOutput {
   // 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 rule of rules) {
-    const parts = generateAdaptationRuleRules(rule);
+  for (const [index, rule] of rules.entries()) {
+    const parts = generateAdaptationRuleRules(
+      rule,
+      `adaptations[${index}].`,
+      sink,
+    );
     if (parts.length === 0) {
       continue;
     }
@@ -1029,12 +1210,9 @@ export function generateAdaptationCSS(theme: DefinedTheme): ThemeCSSOutput {
   return {prose: '', component: blocks.join('\n\n')};
 }
 
-/** Indent a generated rule one level further, for nesting inside `@media`. */
+/** Indent the rule start without rewriting newlines inside authored values. */
 function indentRule(rule: string): string {
-  return rule
-    .split('\n')
-    .map(line => (line.length > 0 ? `  ${line}` : line))
-    .join('\n');
+  return `  ${rule}`;
 }
 
 /**
@@ -1075,8 +1253,11 @@ export function generateDataTokenDefaultsCSS(): string {
  * The theme-independent `--color-data-*` defaults are not part of this output:
  * see `generateDataTokenDefaultsCSS`.
  */
-export function generateThemeCSS(theme: DefinedTheme): ThemeCSSOutput {
-  const {component, prose} = generateThemeRulesSplit(theme);
+export function generateThemeCSS(
+  theme: DefinedTheme,
+  warnings?: string[],
+): ThemeCSSOutput {
+  const {component, prose} = generateThemeRulesSplit(theme, warnings);
   const scopeSelector = themeScopeStart(theme.name);
   const scopeTo = THEME_SCOPE_TO;
 
@@ -1096,14 +1277,14 @@ export function generateThemeCSS(theme: DefinedTheme): ThemeCSSOutput {
 
   // Adaptations follow the root theme in authored order. Media-surface rules
   // follow adaptations so onDark/onLight keep their specified precedence.
-  const adaptationCss = generateAdaptationCSS(theme);
+  const adaptationCss = generateAdaptationCSS(theme, warnings);
   if (adaptationCss.component) {
     componentCss = componentCss
       ? `${componentCss}\n\n${adaptationCss.component}`
       : adaptationCss.component;
   }
 
-  const onMediaCss = generateOnMediaCSS(theme);
+  const onMediaCss = generateOnMediaCSS(theme, warnings);
   if (onMediaCss) {
     componentCss = componentCss
       ? `${componentCss}\n\n${onMediaCss}`

package/src/theme/themeAdaptations.test.ts

@@ -3,7 +3,8 @@
 /**
  * @file themeAdaptations.test.ts
  * Tests AST-012's ordered, closed, CSS-first theme adaptation contract,
- * including normalization and final reachable-cascade validation.
+ * including normalization, root-dependent type-scale component writes, and final
+ * reachable-cascade validation.
  */
 
 import {describe, expect, it} from 'vitest';
@@ -378,6 +379,215 @@ describe('rule order and writes', () => {
   });
 });
 
+describe('adapted type-scale component defaults', () => {
+  const displayFamily = 'Sarina, "Brush Script MT", "Snell Roundhand", cursive';
+  const butterShapedInput: DefineThemeInput = {
+    name: 'butter-shaped',
+    typography: {
+      scale: {base: 16, ratio: 1.25},
+      body: {family: 'Outfit', fallbacks: 'sans-serif'},
+    },
+    components: {
+      text: Object.fromEntries(
+        ['display-1', 'display-2', 'display-3'].map(type => [
+          `type:${type}`,
+          {fontFamily: displayFamily},
+        ]),
+      ),
+      button: {base: {borderRadius: '12px'}},
+    },
+    adaptations: {
+      rules: [
+        {
+          when: {width: {below: 'md'}, pointer: 'coarse'},
+          value: {typography: {scale: {base: 14, ratio: 1.2}}},
+        },
+      ],
+    },
+  };
+
+  it('keeps butter-shaped display families while adapting scale tokens only', () => {
+    const theme = defineTheme(butterShapedInput);
+    const rule = theme.__adaptationRules![0];
+    const css = generateThemeCSS(theme).component;
+    const adaptiveCSS = generateAdaptationCSS(theme).component;
+
+    expect(rule.query).toBe('(width < 768px) and (pointer: coarse)');
+    expect(theme.tokens['--font-size-base']).toBe('1rem');
+    expect(rule.tokens['--font-size-base']).toBe('0.875rem');
+    expect(rule.tokens['--font-size-5xl']).not.toBe(
+      theme.tokens['--font-size-5xl'],
+    );
+    expect(adaptiveCSS).toContain('--font-size-base: 0.875rem');
+    // The root owns the var() wiring and its authored overrides. Re-emitting
+    // either would turn an unrelated scale change into a component write.
+    expect(rule.components).toBeUndefined();
+    expect(adaptiveCSS).not.toContain('.astryx-text');
+    expect(adaptiveCSS).not.toContain('.astryx-heading');
+    expect(adaptiveCSS).not.toContain('.astryx-button');
+    for (const type of ['display-1', 'display-2', 'display-3']) {
+      expect(theme.components?.text[`type:${type}`].fontFamily).toBe(
+        displayFamily,
+      );
+      expect(count(css, `.astryx-text[data-type="${type}"] {`)).toBe(1);
+    }
+    expect(count(css, `font-family: ${displayFamily};`)).toBe(3);
+    // Built modules retain root components + intent, not resolved rule layers.
+    expect(generateThemeCSS({...theme, __adaptationRules: undefined})).toEqual(
+      generateThemeCSS(theme),
+    );
+  });
+
+  it('fills only missing generated leaves when the root has no scale', () => {
+    const components = {
+      heading: {
+        'level:1': {fontFamily: 'serif', fontWeight: '900'},
+        'type:display-1': {fontSize: '5rem'},
+      },
+      text: {
+        'type:display-1': {fontFamily: displayFamily, lineHeight: '1.1'},
+        'type:body': {fontSize: '18px'},
+        'type:custom': {fontFamily: 'monospace'},
+      },
+      button: {base: {borderRadius: '12px'}},
+    };
+    const before = structuredClone(components);
+    const theme = defineTheme({
+      ...butterShapedInput,
+      typography: undefined,
+      components,
+    });
+    const generated = theme.__adaptationRules![0].components!;
+
+    expect(generated.heading['level:1']).toEqual({
+      fontSize: 'var(--text-heading-1-size)',
+      lineHeight: 'var(--text-heading-1-leading)',
+    });
+    expect(generated.heading['type:display-1']).toEqual({
+      fontFamily: 'var(--font-family-heading)',
+      lineHeight: 'var(--text-display-1-leading)',
+    });
+    expect(generated.text['type:display-1']).toEqual({
+      fontSize: 'var(--text-display-1-size)',
+    });
+    expect(generated.text['type:body']).toEqual({
+      fontFamily: 'var(--font-family-body)',
+      lineHeight: 'var(--text-body-leading)',
+    });
+    expect(generated.text['type:custom']).toBeUndefined();
+    expect(generated.button).toBeUndefined();
+    expect(components).toEqual(before);
+    expect(theme.components).toEqual(before);
+  });
+
+  it('preserves explicit rule writes, including a later root-restoring value', () => {
+    const theme = defineTheme({
+      ...butterShapedInput,
+      adaptations: {
+        rules: [
+          {
+            when: {pointer: 'coarse'},
+            value: {
+              typography: {scale: {base: 15}},
+              components: {
+                text: {'type:display-1': {fontFamily: 'monospace'}},
+                heading: {'level:1': {fontWeight: '300'}},
+              },
+            },
+          },
+          ...butterShapedInput.adaptations!.rules!,
+          {
+            when: {contrast: 'more'},
+            value: {
+              typography: {scale: {base: 14}},
+              components: {
+                text: {'type:display-1': {fontFamily: displayFamily}},
+              },
+            },
+          },
+        ],
+      },
+    });
+    const [first, scaleOnly, restore] = theme.__adaptationRules!;
+    expect(first.components).toEqual({
+      text: {'type:display-1': {fontFamily: 'monospace'}},
+      heading: {'level:1': {fontWeight: '300'}},
+    });
+    expect(scaleOnly.components).toBeUndefined();
+    expect(restore.components).toEqual({
+      text: {'type:display-1': {fontFamily: displayFamily}},
+    });
+    const css = generateAdaptationCSS(theme).component;
+    expect(css.indexOf('font-family: monospace')).toBeLessThan(
+      css.indexOf(`font-family: ${displayFamily}`),
+    );
+    // Explicit heading defaults still trigger the public weight-prop guard.
+    expect(css).toContain(
+      '.astryx-heading[data-weight="bold"] { font-weight: var(--font-weight-bold); }',
+    );
+  });
+
+  it('lets a later generated component leaf win when its root path is absent', () => {
+    const theme = defineTheme(
+      adaptationInput([
+        {
+          when: {pointer: 'coarse'},
+          value: {components: {text: {'type:body': {fontSize: '2rem'}}}},
+        },
+        {
+          when: {pointer: 'coarse'},
+          value: {typography: {scale: {base: 14, ratio: 1.2}}},
+        },
+      ]),
+    );
+    expect(theme.__axes.typography).toBeUndefined();
+    expect(theme.components).toBeUndefined();
+    const [authored, generated] = theme.__adaptationRules!;
+    expect(authored.components?.text['type:body'].fontSize).toBe('2rem');
+    expect(generated.components?.text['type:body'].fontSize).toBe(
+      'var(--text-body-size)',
+    );
+
+    // FR4/FR6: only existing root paths suppress generated defaults. Without
+    // root wiring, the later scale produces a component write, so it beats the
+    // earlier authored leaf when both conditions match (unlike the case above).
+    const css = generateAdaptationCSS(theme).component;
+    const bodyRules = [
+      ...css.matchAll(/\.astryx-text\[data-type="body"\] \{([^}]+)\}/g),
+    ].map(match => match[1]);
+    expect(bodyRules).toHaveLength(2);
+    expect(bodyRules[0]).toContain('font-size: 2rem;');
+    expect(bodyRules[1]).toContain('font-size: var(--text-body-size);');
+    expect(mediaPreludes(css)).toEqual([
+      '(pointer: coarse)',
+      '(pointer: coarse)',
+    ]);
+    expect(generateThemeCSS({...theme, __adaptationRules: undefined})).toEqual(
+      generateThemeCSS(theme),
+    );
+  });
+
+  it('uses the effective child root without mutating inherited components', () => {
+    const base = defineTheme(butterShapedInput);
+    const before = structuredClone(base.components);
+    const child = defineTheme({
+      name: 'child-display',
+      extends: base,
+      components: {
+        text: {'type:display-2': {fontFamily: 'serif'}},
+        heading: {'level:2': {fontFamily: 'monospace'}},
+      },
+    });
+    expect(child.__adaptationRules![0].components).toBeUndefined();
+    expect(child.components?.text['type:display-1'].fontFamily).toBe(
+      displayFamily,
+    );
+    expect(child.components?.text['type:display-2'].fontFamily).toBe('serif');
+    expect(child.components?.heading['level:2'].fontFamily).toBe('monospace');
+    expect(base.components).toEqual(before);
+  });
+});
+
 describe('theme-local adaptation values', () => {
   const localName = '--astryx-theme-local-root-control-height';