@astryxdesign/core 0.7.4 → 0.7.5-canary.0418c47

package/dist/theme/generateThemeRules.d.ts

@@ -2,8 +2,9 @@
  * @file Theme CSS generation utilities
  *
  * 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.
+ * 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
@@ -22,7 +23,8 @@
  *   for each dropped declaration
  * @position packages/core/src/theme/generateThemeRules.ts
  */
-import type { ComponentStyleMap, DefinedTheme } from './defineTheme';
+import type { ComponentStyleMap, DefinedTheme } from './defineTheme.js';
+import { type ResolvedThemeAdaptationRule } from './themeAdaptations.js';
 /**
  * Structured output from generateThemeRulesSplit.
  * Separates prose element defaults from component/token overrides
@@ -51,6 +53,8 @@ export interface ThemeCSSOutput {
      */
     component: string;
 }
+/** Root status roles a theme leaves unset: INV17-derived values and INV16 aliases. */
+export declare function generatedScopedStatusRoleDefaults(tokens: Record<string, string>, localTokens?: Record<string, string>, rules?: ReadonlyArray<ResolvedThemeAdaptationRule>): [string, string][];
 /**
  * Generate the intermediary CSS rules for a theme.
  *

package/dist/theme/generateThemeRules.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"generateThemeRules.d.ts","sourceRoot":"","sources":["../../src/theme/generateThemeRules.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAEH,OAAO,KAAK,EAAC,iBAAiB,EAAE,YAAY,EAAC,MAAM,eAAe,CAAC;AAoHnE;;;;GAIG;AACH,MAAM,WAAW,eAAe;IAC9B,+EAA+E;IAC/E,SAAS,EAAE,MAAM,EAAE,CAAC;IACpB,kFAAkF;IAClF,KAAK,EAAE,MAAM,EAAE,CAAC;CACjB;AAED;;GAEG;AACH,MAAM,WAAW,cAAc;IAC7B;;;;OAIG;IACH,KAAK,EAAE,MAAM,CAAC;IACd;;;;OAIG;IACH,SAAS,EAAE,MAAM,CAAC;CACnB;AAmUD;;;;;GAKG;AACH;;;;;;;GAOG;AACH,MAAM,WAAW,eAAe;IAC9B,sCAAsC;IACtC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC/B,yCAAyC;IACzC,WAAW,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACrC,0CAA0C;IAC1C,UAAU,CAAC,EAAE,iBAAiB,CAAC;CAChC;AAED,wBAAgB,kBAAkB,CAChC,KAAK,EAAE,eAAe,EACtB,QAAQ,CAAC,EAAE,MAAM,EAAE,GAClB,MAAM,EAAE,CAiDV;AAoZD;;;;;;;;;GASG;AACH,wBAAgB,uBAAuB,CACrC,KAAK,EAAE,YAAY,EACnB,QAAQ,CAAC,EAAE,MAAM,EAAE,GAClB,eAAe,CAejB;AAED;;;;;;;GAOG;AACH,wBAAgB,kBAAkB,CAChC,KAAK,EAAE,YAAY,EACnB,QAAQ,CAAC,EAAE,MAAM,EAAE,GAClB,MAAM,CAmDR;AA+CD;;;;;;;;GAQG;AACH,wBAAgB,qBAAqB,CACnC,KAAK,EAAE,YAAY,EACnB,QAAQ,CAAC,EAAE,MAAM,EAAE,GAClB,cAAc,CAqFhB;AAOD;;;;;;;;;;;;;GAaG;AACH,wBAAgB,gBAAgB,CAC9B,KAAK,EAAE,YAAY,EACnB,QAAQ,CAAC,EAAE,MAAM,EAAE,GAClB,cAAc,CAoChB"}
+{"version":3,"file":"generateThemeRules.d.ts","sourceRoot":"","sources":["../../src/theme/generateThemeRules.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAEH,OAAO,KAAK,EAAC,iBAAiB,EAAE,YAAY,EAAC,MAAM,eAAe,CAAC;AACnE,OAAO,EAGL,KAAK,2BAA2B,EACjC,MAAM,oBAAoB,CAAC;AAmH5B;;;;GAIG;AACH,MAAM,WAAW,eAAe;IAC9B,+EAA+E;IAC/E,SAAS,EAAE,MAAM,EAAE,CAAC;IACpB,kFAAkF;IAClF,KAAK,EAAE,MAAM,EAAE,CAAC;CACjB;AAED;;GAEG;AACH,MAAM,WAAW,cAAc;IAC7B;;;;OAIG;IACH,KAAK,EAAE,MAAM,CAAC;IACd;;;;OAIG;IACH,SAAS,EAAE,MAAM,CAAC;CACnB;AAyhBD,sFAAsF;AACtF,wBAAgB,iCAAiC,CAC/C,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,EAC9B,WAAW,GAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAM,EACxC,KAAK,GAAE,aAAa,CAAC,2BAA2B,CAAM,GACrD,CAAC,MAAM,EAAE,MAAM,CAAC,EAAE,CAqDpB;AA+OD;;;;;GAKG;AACH;;;;;;;GAOG;AACH,MAAM,WAAW,eAAe;IAC9B,sCAAsC;IACtC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC/B,yCAAyC;IACzC,WAAW,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACrC,0CAA0C;IAC1C,UAAU,CAAC,EAAE,iBAAiB,CAAC;CAChC;AA4FD,wBAAgB,kBAAkB,CAChC,KAAK,EAAE,eAAe,EACtB,QAAQ,CAAC,EAAE,MAAM,EAAE,GAClB,MAAM,EAAE,CA6DV;AAoZD;;;;;;;;;GASG;AACH,wBAAgB,uBAAuB,CACrC,KAAK,EAAE,YAAY,EACnB,QAAQ,CAAC,EAAE,MAAM,EAAE,GAClB,eAAe,CAejB;AA8BD;;;;;;;GAOG;AACH,wBAAgB,kBAAkB,CAChC,KAAK,EAAE,YAAY,EACnB,QAAQ,CAAC,EAAE,MAAM,EAAE,GAClB,MAAM,CA+GR;AAmDD;;;;;;;;GAQG;AACH,wBAAgB,qBAAqB,CACnC,KAAK,EAAE,YAAY,EACnB,QAAQ,CAAC,EAAE,MAAM,EAAE,GAClB,cAAc,CAgGhB;AAOD;;;;;;;;;;;;;GAaG;AACH,wBAAgB,gBAAgB,CAC9B,KAAK,EAAE,YAAY,EACnB,QAAQ,CAAC,EAAE,MAAM,EAAE,GAClB,cAAc,CAWhB"}

package/dist/theme/generateThemeRules.js

@@ -4,8 +4,9 @@
  * @file Theme CSS generation utilities
  *
  * 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.
+ * 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
@@ -28,8 +29,9 @@
 import { normalizeThemeAdaptations, resolveThemeAdaptationRules } from "./themeAdaptations.js";
 import { parseStyleKey } from "../utils/parseStyleKey.js";
 import { getDerivedVars } from "./derivedVarRegistry.js";
+import { STATUS_NAMES, deriveStatusRoleTokens } from "./statusRoleDerivation.js";
 import { cssVar, classPrefix, dataAttrNamespace } from "../naming.js";
-import { checkDeclarationName, checkDeclarationValue } from "./declarationBoundary.js";
+import { analyzeDeclarationValue, canonicalizeDeclarationName, checkDeclarationName, checkDeclarationValue } from "./declarationBoundary.js";
 
 /**
  * Theme @scope selectors.
@@ -342,7 +344,7 @@ function joinDeclarations(entries, location, sink, mapProp = p => p) {
   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 value = stringifyTokenValue(rawValue);
     const prop = mapProp(rawProp);
     if (acceptDeclaration(prop, value, location, sink)) {
       lines.push(`    ${prop}: ${value};`);
@@ -351,10 +353,332 @@ function joinDeclarations(entries, location, sink, mapProp = p => p) {
   return lines.join('\n');
 }
 
+/**
+ * Public status roles whose canonical default references an existing semantic
+ * source token. StyleX owns the document defaults. A theme that authors a
+ * source repeats its omitted role 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_STATUS_ROLE_DEFAULTS = [['--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']];
+const SCOPED_STATUS_ROLE_SOURCES = new Map(SCOPED_STATUS_ROLE_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_STATUS_ROLE_DEFAULTS.map(([role], index) => [role, index]));
+function stringifyTokenValue(value) {
+  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);
+}
+function assignTokenCascade(state, ...tokenSets) {
+  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) {
+  const state = {
+    values: {},
+    important: new Set()
+  };
+  assignTokenCascade(state, ...tokenSets);
+  return state;
+}
+
+/** Check whether one candidate value closes a cycle through its own role. */
+function tokenValuesWouldHaveCycleWithValue(tokens, relevantToken, candidateValue) {
+  const stack = [...analyzeDeclarationValue(candidateValue).references];
+  const visited = new Set();
+  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
+};
+function adaptationConditionMatchesCell(condition, widthRank, pointer, contrast, motion) {
+  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();
+
+/** Every reachable ordered adaptation-rule match set, including the root. */
+function reachableAdaptationMatchSets(rules) {
+  const cached = REACHABLE_MATCH_SET_CACHE.get(rules);
+  if (cached !== undefined) {
+    return cached;
+  }
+  const matchSets = new Map();
+  for (let widthRank = 0; widthRank <= 5; widthRank++) {
+    for (const pointer of ['coarse', 'fine', 'none']) {
+      for (const contrast of ['more', 'less', 'no-preference', 'custom']) {
+        for (const motion of ['reduce', 'no-preference']) {
+          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, rootLocalTokens, rootAliases, rules, matchingRuleIndexes, conditionalAliases = []) {
+  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) {
+  if (!('__adaptations' in theme) && !('__adaptationRules' in theme)) {
+    return [];
+  }
+  return resolvedAdaptationRules(theme);
+}
+
+/** Root status roles a theme leaves unset: INV17-derived values and INV16 aliases. */
+export function generatedScopedStatusRoleDefaults(tokens, localTokens = {}, rules = []) {
+  // 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 = 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_STATUS_ROLE_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) {
+  const canonicalTokens = createTokenCascade(tokens).values;
+  return SCOPED_STATUS_ROLE_DEFAULTS.flatMap(([role]) => {
+    const value = canonicalTokens[role];
+    return value === undefined ? [] : [[role, stringifyTokenValue(value)]];
+  });
+}
+function tokenValueIsAliasOf(value, source) {
+  return analyzeDeclarationValue(stringifyTokenValue(value)).singleVarReference === source;
+}
+function mediaRoleRestorationValue(role, value) {
+  const source = SCOPED_STATUS_ROLE_SOURCES.get(role);
+  return source !== undefined && tokenValueIsAliasOf(value, source) ? value : 'inherit';
+}
+function generatedAdaptationStatusRoleDefaults(rootTokens, rootLocalTokens, rules, rootAliases) {
+  const aliases = rules.map(() => []);
+  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_STATUS_ROLE_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, rootTokens, rootLocalTokens, rules, rootAliases) {
+  const aliases = [];
+  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, alias, matchingRuleIndexes) => {
+    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_STATUS_ROLE_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, location, sink) {
-  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;
+function tokenBlock(source, location, sink, tokenEntries = Object.entries(source.tokens)) {
+  const declarations = [joinDeclarations(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;
 }
 
@@ -382,6 +706,39 @@ function componentLocation(prefix, component, key) {
  * lost for every conditional rule, with no type error to catch it.
  */
 
+const STATUS_ROLE_GENERATION_CACHE = new WeakMap();
+let activeStatusRoleGeneration;
+function tokenSetSignature(tokens) {
+  return Object.entries(tokens ?? {}).map(([name, value]) => [name, typeof value, stringifyTokenValue(value)]);
+}
+function statusRoleGenerationSignature(theme, rules) {
+  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) {
+  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 = {
+    theme,
+    rules,
+    rootAliases: generatedScopedStatusRoleDefaults(theme.tokens, theme.localTokens, rules)
+  };
+  STATUS_ROLE_GENERATION_CACHE.set(theme, {
+    signature,
+    context
+  });
+  return context;
+}
+function statusRoleGenerationContext(theme) {
+  return activeStatusRoleGeneration?.theme === theme ? activeStatusRoleGeneration : createStatusRoleGenerationContext(theme);
+}
+function adaptationStatusRoleDefaults(context) {
+  context.adaptationAliases ??= generatedAdaptationStatusRoleDefaults(context.theme.tokens, context.theme.localTokens, context.rules, context.rootAliases);
+  return context.adaptationAliases;
+}
 export function generateThemeRules(theme, warnings) {
   const parts = [];
   const sink = diagnosticSink(warnings);
@@ -391,8 +748,12 @@ export function generateThemeRules(theme, warnings) {
   // without duplicating prose selectors inside every media query.
   const val = key => `var(${key})`;
 
-  // 1. Token block — CSS custom properties on :scope
-  const tokenRules = tokenBlock(theme, '', sink);
+  // 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);
   }
@@ -401,8 +762,8 @@ export function generateThemeRules(theme, warnings) {
   // 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.
+  // 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  }`);
   }
@@ -746,6 +1107,19 @@ export function generateThemeRulesSplit(theme, warnings) {
     prose
   };
 }
+function resolvedAdaptationRules(theme) {
+  // 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.
@@ -759,6 +1133,12 @@ export function generateOnMediaCSS(theme, warnings) {
   const parts = [];
   const scopeSelector = themeScopeStart(theme.name);
   const sink = diagnosticSink(warnings);
+  const context = statusRoleGenerationContext(theme);
+  const {
+    rules,
+    rootAliases
+  } = context;
+  const mediaStatusRoleDefaults = new Map();
   for (const surface of ['dark', 'light']) {
     const onMedia = surface === 'dark' ? theme.__onDark : theme.__onLight;
     if (!onMedia) {
@@ -766,8 +1146,11 @@ export function generateOnMediaCSS(theme, warnings) {
     }
     const location = surface === 'dark' ? 'onDark.' : 'onLight.';
 
-    // Token overrides
-    const tokenEntries = Object.entries(onMedia.tokens);
+    // 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) {
       const declarations = joinDeclarations(tokenEntries, `${location}tokens`, sink);
       parts.push(`  ${mediaSelector(surface)} {\n${declarations}\n  }`);
@@ -794,17 +1177,46 @@ export function generateOnMediaCSS(theme, warnings) {
       });
     }
   }
-  if (parts.length === 0) {
+  const adaptationMediaRoleBlocks = [];
+  for (const [index, rule] of rules.entries()) {
+    const authoredRoles = authoredStatusRoleEntries(rule.tokens);
+    if (authoredRoles.length === 0) {
+      continue;
+    }
+    const roleParts = [];
+    for (const surface of ['dark', 'light']) {
+      const onMedia = surface === 'dark' ? theme.__onDark : theme.__onLight;
+      if (!onMedia) {
+        continue;
+      }
+      const generatedRoles = new Set((mediaStatusRoleDefaults.get(surface) ?? []).map(([role]) => role));
+      const restorationEntries = 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 inner = parts.join('\n\n');
-  return `@scope (${scopeSelector}) to (${THEME_SCOPE_TO}) {\n${inner}\n}`;
+  const blocks = [];
+  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, location, sink) {
+function generateAdaptationRuleRules(rule, location, sink, statusRoleDefaults) {
   const parts = [];
-  const tokens = tokenBlock(rule, location, sink);
+  const tokens = tokenBlock(rule, location, sink, [...Object.entries(rule.tokens), ...statusRoleDefaults]);
   if (tokens !== null) {
     parts.push(tokens);
   }
@@ -839,11 +1251,13 @@ function generateAdaptationMediaBlock(query, parts, scopeSelector) {
 export function generateAdaptationCSS(theme, warnings) {
   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.
-  const normalizedAdaptations = theme.__adaptations === undefined ? undefined : normalizeThemeAdaptations(theme.name, theme.__adaptations, undefined);
-  const rules = theme.__adaptationRules ?? (normalizedAdaptations ? resolveThemeAdaptationRules(theme.name, normalizedAdaptations, theme.__axes ?? {}, theme.tokens, theme.localTokens, theme.components) : undefined);
-  if (!rules || rules.length === 0) {
+  // 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: ''
@@ -852,6 +1266,7 @@ export function generateAdaptationCSS(theme, warnings) {
   const scopeSelector = themeScopeStart(theme.name);
   const blocks = [];
   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
@@ -859,12 +1274,29 @@ export function generateAdaptationCSS(theme, warnings) {
   // 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);
+    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
@@ -914,6 +1346,18 @@ function indentRule(rule) {
  * generator emits only a theme's explicitly authored token overrides.
  */
 export function generateThemeCSS(theme, warnings) {
+  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, warnings) {
   const {
     component,
     prose