@astryxdesign/core 0.7.5 → 0.7.6-canary.0ef60dd

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

@@ -0,0 +1 @@
+{"version":3,"file":"motionKnobs.d.ts","sourceRoot":"","sources":["../../src/theme/motionKnobs.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;GAcG;AAEH,yCAAyC;AACzC,MAAM,MAAM,eAAe,GAAG,OAAO,GAAG,UAAU,GAAG,YAAY,CAAC;AAElE;;;GAGG;AACH,MAAM,MAAM,kBAAkB,GAAG,QAAQ,CAAC;AAE1C,0DAA0D;AAC1D,MAAM,WAAW,gBAAgB;IAC/B;;;OAGG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC;IACf;;;;OAIG;IACH,SAAS,CAAC,EAAE,eAAe,CAAC;CAC7B;AAED,mEAAmE;AACnE,MAAM,WAAW,mBAAmB;IAClC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,SAAS,EAAE,eAAe,CAAC;IACpC,QAAQ,CAAC,aAAa,EAAE,kBAAkB,CAAC;IAC3C;;;;OAIG;IACH,QAAQ,CAAC,UAAU,EAAE,OAAO,CAAC;CAC9B;AAED,uCAAuC;AACvC,eAAO,MAAM,WAAW;;;CAAiC,CAAC;AAQ1D,kEAAkE;AAClE,wBAAgB,YAAY,CAC1B,MAAM,EAAE,gBAAgB,GAAG,SAAS,GACnC,mBAAmB,CAcrB"}

package/dist/theme/motionKnobs.js

@@ -0,0 +1,48 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file motionKnobs.ts
+ * @input A theme's motion knobs (`tempo`, `character`)
+ * @output Their types and `resolveMotionKnobs`, which fills in the defaults
+ *   and clamps `tempo` (`spec:AST-108` FR1). `reducedMotion` is not a public
+ *   knob until `'always'` ships: every theme resolves to `'system'`
+ * @position Theme utility with no imports: themeMotion.ts builds the motion
+ *   tokens on it, and the motion foundation reads a theme's knobs through it
+ *   without loading the token stylesheet. Pure; safe on the server and in
+ *   plain Node.
+ *
+ * SYNC: When modified, update:
+ * - /packages/core/src/theme/themeMotion.ts (re-exports these)
+ * - /packages/core/src/theme/themeMotion.test.ts
+ */
+
+/** How lively a theme's motion feels. */
+
+/**
+ * Whose Reduce Motion setting a theme follows: `'system'`, each person's own.
+ * Internal: no theme sets it until `'always'` ships (`spec:AST-108` FR6).
+ */
+
+/** The motion knobs a theme sets (`spec:AST-108` FR1). */
+
+/** The knobs with their defaults filled in and `tempo` clamped. */
+
+/** The range `tempo` is clamped to. */
+export const TEMPO_RANGE = {
+  min: 0.75,
+  max: 1.5
+};
+const CHARACTERS = ['crisp', 'standard', 'expressive'];
+
+/** The knobs of `config`, defaults filled in, `tempo` clamped. */
+export function resolveKnobs(config) {
+  const tempoIsSet = typeof config?.tempo === 'number' && Number.isFinite(config.tempo);
+  const tempo = tempoIsSet ? Math.min(TEMPO_RANGE.max, Math.max(TEMPO_RANGE.min, config.tempo)) : 1;
+  const character = config?.character != null && CHARACTERS.includes(config.character) ? config.character : 'standard';
+  return {
+    tempo,
+    character,
+    reducedMotion: 'system',
+    tempoIsSet
+  };
+}

package/dist/theme/resolveThemeValues.d.ts

@@ -24,7 +24,7 @@ import type { ComponentStyleMap, TokenName, TokenValue } from './defineTheme.js'
 import type { TypographyConfig, FontWeight } from './types.js';
 import type { SyntaxThemeDefinition } from './syntax/index.js';
 import { type TypeScaleConfig } from './expandTypeScale.js';
-import { type MotionScaleConfig } from './expandMotionScale.js';
+import { type MotionCharacter, type ThemeMotionConfig } from './themeMotion.js';
 import { type RadiusScaleConfig } from './expandRadiusScale.js';
 import { type ColorScaleConfig } from './expandColorScale.js';
 /**
@@ -41,8 +41,8 @@ export interface ThemeValuesInput {
     color?: ColorScaleConfig;
     /** Radius scale configuration. */
     radius?: RadiusScaleConfig;
-    /** Motion scale configuration. */
-    motion?: MotionScaleConfig;
+    /** Motion: the three knobs, a motion scale configuration, or both. */
+    motion?: ThemeMotionConfig;
     /** Syntax highlighting theme. */
     syntax?: SyntaxThemeDefinition;
     /** Explicit token overrides — highest precedence. */
@@ -118,7 +118,14 @@ export declare function buildFontFamilyTokens(typo: TypographyConfig): Record<st
  * `extends`, or nothing for a root theme. It sits below everything this input
  * declares.
  */
-export declare function resolveThemeValues(input: ThemeValuesInput, seed?: ThemeValuesSeed, { strictTokens }?: {
+export declare function resolveThemeValues(input: ThemeValuesInput, seed?: ThemeValuesSeed, { strictTokens, inheritedCharacter, standardBeneath, }?: {
     strictTokens?: boolean;
+    /**
+     * The motion character in effect beneath this layer, from a base theme or
+     * the theme an adaptation rule belongs to, for a layer that sets none.
+     */
+    inheritedCharacter?: MotionCharacter;
+    /** The --ease-standard beneath a layer resolved without a seed: a rule's theme's. */
+    standardBeneath?: string;
 }): ResolvedThemeValues;
 //# sourceMappingURL=resolveThemeValues.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"resolveThemeValues.d.ts","sourceRoot":"","sources":["../../src/theme/resolveThemeValues.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAEH,OAAO,KAAK,EAAC,iBAAiB,EAAE,SAAS,EAAE,UAAU,EAAC,MAAM,eAAe,CAAC;AAC5E,OAAO,KAAK,EAAC,gBAAgB,EAAE,UAAU,EAAC,MAAM,SAAS,CAAC;AAC1D,OAAO,KAAK,EAAC,qBAAqB,EAAC,MAAM,UAAU,CAAC;AACpD,OAAO,EAGL,KAAK,eAAe,EACrB,MAAM,mBAAmB,CAAC;AAC3B,OAAO,EAAoB,KAAK,iBAAiB,EAAC,MAAM,qBAAqB,CAAC;AAC9E,OAAO,EAAoB,KAAK,iBAAiB,EAAC,MAAM,qBAAqB,CAAC;AAC9E,OAAO,EAAmB,KAAK,gBAAgB,EAAC,MAAM,oBAAoB,CAAC;AAO3E;;;;;;GAMG;AACH,MAAM,WAAW,gBAAgB;IAC/B,8CAA8C;IAC9C,UAAU,CAAC,EAAE,gBAAgB,CAAC;IAC9B,iCAAiC;IACjC,KAAK,CAAC,EAAE,gBAAgB,CAAC;IACzB,kCAAkC;IAClC,MAAM,CAAC,EAAE,iBAAiB,CAAC;IAC3B,kCAAkC;IAClC,MAAM,CAAC,EAAE,iBAAiB,CAAC;IAC3B,iCAAiC;IACjC,MAAM,CAAC,EAAE,qBAAqB,CAAC;IAC/B,qDAAqD;IACrD,MAAM,CAAC,EAAE,OAAO,CAAC,MAAM,CAAC,SAAS,EAAE,UAAU,CAAC,CAAC,CAAC;IAChD,iCAAiC;IACjC,UAAU,CAAC,EAAE,iBAAiB,CAAC;CAChC;AAED,2EAA2E;AAC3E,MAAM,WAAW,eAAe;IAC9B,6BAA6B;IAC7B,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAChC,iCAAiC;IACjC,UAAU,CAAC,EAAE,iBAAiB,CAAC;CAChC;AAED,8CAA8C;AAC9C,MAAM,WAAW,mBAAmB;IAClC,iCAAiC;IACjC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC/B,kDAAkD;IAClD,UAAU,CAAC,EAAE,iBAAiB,CAAC;CAChC;AAMD;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,iBAAiB,CAC/B,KAAK,EAAE,UAAU,EACjB,EAAC,MAAc,EAAC,GAAE;IAAC,MAAM,CAAC,EAAE,OAAO,CAAA;CAAM,GACxC,MAAM,CAyBR;AAED;;;GAGG;AACH,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,UAAU,GAAG,MAAM,CAQ5D;AAED;;;GAGG;AACH,wBAAgB,eAAe,CAC7B,MAAM,CAAC,EAAE,MAAM,EACf,SAAS,CAAC,EAAE,MAAM,GACjB,MAAM,GAAG,SAAS,CASpB;AAMD;;;;;;GAMG;AACH,wBAAgB,oBAAoB,CAClC,IAAI,EAAE,gBAAgB,GACrB,eAAe,GAAG,SAAS,CA+C7B;AAED;;;GAGG;AACH,wBAAgB,qBAAqB,CACnC,IAAI,EAAE,gBAAgB,GACrB,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAoBxB;AAMD;;;;;;GAMG;AACH,wBAAgB,kBAAkB,CAChC,KAAK,EAAE,gBAAgB,EACvB,IAAI,CAAC,EAAE,eAAe,EACtB,EAAC,YAAoB,EAAC,GAAE;IAAC,YAAY,CAAC,EAAE,OAAO,CAAA;CAAM,GACpD,mBAAmB,CA+DrB"}
+{"version":3,"file":"resolveThemeValues.d.ts","sourceRoot":"","sources":["../../src/theme/resolveThemeValues.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAEH,OAAO,KAAK,EAAC,iBAAiB,EAAE,SAAS,EAAE,UAAU,EAAC,MAAM,eAAe,CAAC;AAC5E,OAAO,KAAK,EAAC,gBAAgB,EAAE,UAAU,EAAC,MAAM,SAAS,CAAC;AAC1D,OAAO,KAAK,EAAC,qBAAqB,EAAC,MAAM,UAAU,CAAC;AACpD,OAAO,EAGL,KAAK,eAAe,EACrB,MAAM,mBAAmB,CAAC;AAC3B,OAAO,EAGL,KAAK,eAAe,EACpB,KAAK,iBAAiB,EACvB,MAAM,eAAe,CAAC;AACvB,OAAO,EAAoB,KAAK,iBAAiB,EAAC,MAAM,qBAAqB,CAAC;AAE9E,OAAO,EAAmB,KAAK,gBAAgB,EAAC,MAAM,oBAAoB,CAAC;AAO3E;;;;;;GAMG;AACH,MAAM,WAAW,gBAAgB;IAC/B,8CAA8C;IAC9C,UAAU,CAAC,EAAE,gBAAgB,CAAC;IAC9B,iCAAiC;IACjC,KAAK,CAAC,EAAE,gBAAgB,CAAC;IACzB,kCAAkC;IAClC,MAAM,CAAC,EAAE,iBAAiB,CAAC;IAC3B,sEAAsE;IACtE,MAAM,CAAC,EAAE,iBAAiB,CAAC;IAC3B,iCAAiC;IACjC,MAAM,CAAC,EAAE,qBAAqB,CAAC;IAC/B,qDAAqD;IACrD,MAAM,CAAC,EAAE,OAAO,CAAC,MAAM,CAAC,SAAS,EAAE,UAAU,CAAC,CAAC,CAAC;IAChD,iCAAiC;IACjC,UAAU,CAAC,EAAE,iBAAiB,CAAC;CAChC;AAED,2EAA2E;AAC3E,MAAM,WAAW,eAAe;IAC9B,6BAA6B;IAC7B,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAChC,iCAAiC;IACjC,UAAU,CAAC,EAAE,iBAAiB,CAAC;CAChC;AAED,8CAA8C;AAC9C,MAAM,WAAW,mBAAmB;IAClC,iCAAiC;IACjC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC/B,kDAAkD;IAClD,UAAU,CAAC,EAAE,iBAAiB,CAAC;CAChC;AAMD;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,iBAAiB,CAC/B,KAAK,EAAE,UAAU,EACjB,EAAC,MAAc,EAAC,GAAE;IAAC,MAAM,CAAC,EAAE,OAAO,CAAA;CAAM,GACxC,MAAM,CAyBR;AAED;;;GAGG;AACH,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,UAAU,GAAG,MAAM,CAQ5D;AAED;;;GAGG;AACH,wBAAgB,eAAe,CAC7B,MAAM,CAAC,EAAE,MAAM,EACf,SAAS,CAAC,EAAE,MAAM,GACjB,MAAM,GAAG,SAAS,CASpB;AAMD;;;;;;GAMG;AACH,wBAAgB,oBAAoB,CAClC,IAAI,EAAE,gBAAgB,GACrB,eAAe,GAAG,SAAS,CA+C7B;AAED;;;GAGG;AACH,wBAAgB,qBAAqB,CACnC,IAAI,EAAE,gBAAgB,GACrB,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAoBxB;AAMD;;;;;;GAMG;AACH,wBAAgB,kBAAkB,CAChC,KAAK,EAAE,gBAAgB,EACvB,IAAI,CAAC,EAAE,eAAe,EACtB,EACE,YAAoB,EACpB,kBAAkB,EAClB,eAAe,GAChB,GAAE;IACD,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB;;;OAGG;IACH,kBAAkB,CAAC,EAAE,eAAe,CAAC;IACrC,qFAAqF;IACrF,eAAe,CAAC,EAAE,MAAM,CAAC;CACrB,GACL,mBAAmB,CA0GrB"}

package/dist/theme/resolveThemeValues.js

@@ -24,8 +24,9 @@
  */
 
 import { expandTypeScale, generateTypeScaleComponents } from "./expandTypeScale.js";
-import { expandMotionScale } from "./expandMotionScale.js";
+import { expandThemeMotion, preTempoName } from "./themeMotion.js";
 import { expandRadiusScale } from "./expandRadiusScale.js";
+import { easeDefaults } from "./tokens.stylex.js";
 import { expandColorScale } from "./expandColorScale.js";
 import { deepMergeComponents } from "./mergeComponents.js";
 
@@ -212,7 +213,9 @@ export function buildFontFamilyTokens(typo) {
  * declares.
  */
 export function resolveThemeValues(input, seed, {
-  strictTokens = false
+  strictTokens = false,
+  inheritedCharacter,
+  standardBeneath
 } = {}) {
   const tokens = {
     ...seed?.tokens
@@ -235,9 +238,19 @@ export function resolveThemeValues(input, seed, {
     Object.assign(tokens, expandRadiusScale(input.radius));
   }
 
-  // 4. Motion-generated tokens
+  // 4. Motion-generated tokens (spec:AST-108 FR2, FR5). A layer that writes
+  // durations also writes the copies busy loops read (FR4), so an enclosing
+  // theme's tempo copies never stand in for its own: without a tempo of its
+  // own, they are its durations.
   if (input.motion) {
-    Object.assign(tokens, expandMotionScale(input.motion));
+    const motion = expandThemeMotion(input.motion);
+    Object.assign(tokens, motion);
+    for (const [name, value] of Object.entries(motion)) {
+      const preTempo = preTempoName(name);
+      if (preTempo !== name && !(preTempo in motion)) {
+        tokens[preTempo] = value;
+      }
+    }
   }
 
   // 5. Font family tokens
@@ -256,11 +269,34 @@ export function resolveThemeValues(input, seed, {
   // 7. Explicit token overrides — highest precedence within this input layer.
   // A generated axis in the same root or adaptation value cannot beat them.
   if (input.tokens) {
+    const own = input.tokens;
     for (const [key, value] of Object.entries(input.tokens)) {
       if (value !== undefined) {
         tokens[key] = resolveTokenValue(value, {
           strict: strictTokens
         });
+        // An explicit duration beats tempo, so a busy loop reading the
+        // pre-tempo value reads it too (spec:AST-108 FR4).
+        const preTempo = preTempoName(key);
+        if (preTempo !== key && own[preTempo] === undefined) {
+          tokens[preTempo] = tokens[key];
+        }
+      }
+    }
+  }
+
+  // At 'standard', --ease-entrance and --ease-move equal the resolved
+  // --ease-standard (spec:AST-108 FR2): the layer's own, else the one beneath
+  // it. A layer that sets them itself, or whose character, its own or the one
+  // it inherits, picks its own curve, keeps them.
+  const own = input.tokens ?? {};
+  const ownCharacter = input.motion != null && 'character' in input.motion ? input.motion.character : undefined;
+  const character = ownCharacter ?? inheritedCharacter;
+  if (ownCharacter === 'standard' || own['--ease-standard'] !== undefined && (character === undefined || character === 'standard')) {
+    const standard = tokens['--ease-standard'] ?? standardBeneath ?? easeDefaults['--ease-standard'];
+    for (const name of ['--ease-entrance', '--ease-move']) {
+      if (own[name] === undefined) {
+        tokens[name] = standard;
       }
     }
   }

package/dist/theme/themeAdaptations.d.ts

@@ -24,6 +24,7 @@
 import type { ComponentStyleMap, TokenName, TokenValue } from './defineTheme.js';
 import type { TypographyConfig } from './types.js';
 import type { MotionScaleConfig } from './expandMotionScale.js';
+import type { ThemeMotionConfig, ThemeMotionKnobs } from './themeMotion.js';
 import type { RadiusScaleConfig } from './expandRadiusScale.js';
 import type { ColorScaleConfig } from './expandColorScale.js';
 /** Fixed names for viewport-width tier start points. */
@@ -88,8 +89,11 @@ export interface ThemeAdaptationValue {
     color?: Partial<ColorScaleConfig>;
     /** Radius axis overrides, completed from root metadata. */
     radius?: Partial<RadiusScaleConfig>;
-    /** Motion axis overrides, completed from root metadata. */
-    motion?: Partial<MotionScaleConfig>;
+    /**
+     * Motion axis overrides, completed from root metadata: scale fields, or the
+     * `tempo` and `character` knobs (spec:AST-108 FR5).
+     */
+    motion?: Partial<MotionScaleConfig> & ThemeMotionKnobs;
     /** Portable semantic-token writes. */
     tokens?: Partial<Record<TokenName, TokenValue>>;
     /** Replacements for exact theme-local names enrolled by the root lineage. */
@@ -123,7 +127,7 @@ export interface ThemeGenerativeAxes {
     typography?: TypographyConfig;
     color?: ColorScaleConfig;
     radius?: RadiusScaleConfig;
-    motion?: MotionScaleConfig;
+    motion?: ThemeMotionConfig;
 }
 /** One rule lowered to concrete CSS writes. */
 export interface ResolvedThemeAdaptationRule {

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

@@ -1 +1 @@
-{"version":3,"file":"themeAdaptations.d.ts","sourceRoot":"","sources":["../../src/theme/themeAdaptations.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"themeAdaptations.d.ts","sourceRoot":"","sources":["../../src/theme/themeAdaptations.ts"],"names":[],"mappings":"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"}

package/dist/theme/themeAdaptations.js

@@ -344,20 +344,43 @@ function completeRadius(root, rule, path) {
   };
 }
 function completeMotion(root, rule, path) {
-  const fast = rule.fast ?? root?.fast;
-  const medium = rule.medium ?? root?.medium;
-  const ratio = rule.ratio ?? root?.ratio;
+  // Not a public field, but a plain-JS caller may still pass it.
+  if (rule.reducedMotion !== undefined) {
+    throw new Error(`${path}.reducedMotion is a theme-wide setting: set it on the theme's own ` + `motion, not in an adaptation rule.`);
+  }
+  const tempo = rule.tempo ?? root?.tempo;
+  const character = rule.character ?? root?.character;
+  const knobs = {
+    ...(tempo !== undefined ? {
+      tempo
+    } : {}),
+    ...(character !== undefined ? {
+      character
+    } : {})
+  };
+  if (knobs.tempo !== undefined) {
+    assertFiniteNumber(knobs.tempo, `${path}.tempo`);
+  }
+  const rootScale = root != null && 'fast' in root ? root : {};
+  const writesScale = rule.fast !== undefined || rule.medium !== undefined || rule.ratio !== undefined || rule.slow !== undefined || rule.easing !== undefined;
+  if (!writesScale && 'fast' in rootScale === false) {
+    // Knobs only, over a root with no scale: the knobs generate the tokens.
+    return knobs;
+  }
+  const fast = rule.fast ?? rootScale.fast;
+  const medium = rule.medium ?? rootScale.medium;
+  const ratio = rule.ratio ?? rootScale.ratio;
   if (fast === undefined || medium === undefined || ratio === undefined) {
     throw new Error(`${path} must supply \`fast\`, \`medium\`, and \`ratio\` unless each missing field exists on the effective root motion axis.`);
   }
   assertFiniteNumber(fast, `${path}.fast`);
   assertFiniteNumber(medium, `${path}.medium`);
   assertFiniteNumber(ratio, `${path}.ratio`);
-  const slow = rule.slow ?? root?.slow;
+  const slow = rule.slow ?? rootScale.slow;
   if (slow !== undefined) {
     assertFiniteNumber(slow, `${path}.slow`);
   }
-  const easing = rule.easing ?? root?.easing;
+  const easing = rule.easing ?? rootScale.easing;
   return {
     fast,
     medium,
@@ -367,7 +390,8 @@ function completeMotion(root, rule, path) {
     } : {}),
     ...(easing !== undefined ? {
       easing
-    } : {})
+    } : {}),
+    ...knobs
   };
 }
 function valueToThemeInput(themeName, ruleIndex, value, axes) {
@@ -640,8 +664,13 @@ export function resolveThemeAdaptationRules(themeName, adaptations, axes, rootTo
     // acceptance to preserve, so a malformed token is rejected here rather
     // than emitted. The root path stays lenient for compatibility.
     // SYNC: packages/core/src/theme/resolveThemeValues.ts (resolveTokenValue)
+    // A rule without motion of its own keeps the theme's character, so its
+    // explicit --ease-standard leaves that character's curves alone; one
+    // at 'standard' matches the theme's --ease-standard.
     {
-      strictTokens: true
+      strictTokens: true,
+      inheritedCharacter: axes.motion?.character,
+      standardBeneath: rootTokens['--ease-standard']
     });
     for (const [name, value] of Object.entries(resolved.tokens)) {
       assertConcreteLeaf(value, `defineTheme("${themeName}").adaptations.rules[${index}].value.tokens["${name}"]`);

package/dist/theme/themeMotion.d.ts

@@ -0,0 +1,96 @@
+/**
+ * @file themeMotion.ts
+ * @input A theme's motion configuration: the knobs (`tempo`, `character`),
+ *   the existing `MotionScaleConfig`, or both
+ * @output The resolved knobs, the motion tokens they generate, and
+ *   `resolveThemeMotion`, the internal resolver the animator and server code
+ *   read (`spec:AST-108` FR1, FR2, FR5, FR6)
+ * @position Theme utility; consumed by resolveThemeValues.ts. Pure: no DOM,
+ *   no import-time work, safe on the server.
+ *
+ * `tempo` scales every motion duration token, clamped to 0.75–1.5.
+ * `character` picks the entrance and move curves. Every theme follows each
+ * person's Reduce Motion setting (`reducedMotion` resolves to `'system'`).
+ * No spring reads the knobs yet. With the defaults (tempo 1, `'standard'`, `'system'`) every token is
+ * today's.
+ *
+ * A `MotionScaleConfig` keeps generating its duration tokens, and its fields
+ * win over `tempo` (FR5); explicit `tokens` win over both in
+ * resolveThemeValues.
+ *
+ * SYNC: When modified, update:
+ * - /packages/core/src/theme/themeMotion.test.ts
+ * - /packages/core/src/theme/resolveThemeValues.ts
+ * - /packages/core/src/theme/defineTheme.ts (the `motion` field's docs)
+ */
+import { type MotionScaleConfig } from './expandMotionScale.js';
+import { type ResolvedMotionKnobs, type ThemeMotionKnobs } from './motionKnobs.js';
+export { TEMPO_RANGE, type MotionCharacter, type ResolvedMotionKnobs, type ThemeMotionKnobs, type ThemeReducedMotion, } from './motionKnobs.js';
+/**
+ * A theme's `motion`: the knobs, the existing `MotionScaleConfig`, or both.
+ * A `MotionScaleConfig`'s fields win over `tempo` for the durations they set.
+ */
+export type ThemeMotionConfig = ThemeMotionKnobs | (MotionScaleConfig & ThemeMotionKnobs);
+/**
+ * The entrance and move curve at each character. `'standard'` is the theme's
+ * `--ease-standard`, so a theme that overrides that easing keeps its entrances
+ * on it.
+ */
+export declare const CHARACTER_EASE: {
+    readonly crisp: "cubic-bezier(0, 0, 0.2, 1)";
+    readonly standard: null;
+    readonly expressive: "cubic-bezier(0.3, 1.2, 0.5, 1)";
+};
+/** The knobs of `config`, defaults filled in, `tempo` clamped. */
+export declare function resolveMotionKnobs(config: ThemeMotionConfig | undefined): ResolvedMotionKnobs;
+/**
+ * The private custom property a theme with a `tempo` writes beside its
+ * duration tokens: the press release fade (`utils/interactionOverlay.stylex.ts`)
+ * multiplies its clock by it.
+ */
+export declare const MOTION_TEMPO_PROPERTY = "--_astryx-motion-tempo";
+/** The duration tokens at `tempo`: today's values times it, to the ms. */
+export declare function durationTokensAt(tempo: number): Record<string, string>;
+/**
+ * The private custom property holding a duration token's value before
+ * `tempo` scaled it (`--duration-slow` → `--_astryx-pre-tempo-duration-slow`).
+ * Busy loops (Spinner, Skeleton) read it, falling back to the token, so their
+ * timing follows a duration scale or an explicit token but never `tempo`
+ * (FR4). Private, like every property the knobs add beside the core tokens
+ * (`architecture:theme-tokens` INV1).
+ */
+export declare function preTempoName(token: string): string;
+/**
+ * The motion tokens `config` generates (FR2, FR5): `--duration-*` times
+ * `tempo`, with a `MotionScaleConfig`'s own durations winning, and the
+ * job-named `--ease-entrance` and `--ease-move` at the theme's character.
+ * A knob the config leaves out writes nothing, so a theme extending another
+ * keeps the base's value for it; a knob it sets is written even at its
+ * default, so a child can set a base's tempo back to 1.
+ */
+export declare function expandThemeMotion(config: ThemeMotionConfig): Record<string, string>;
+/** What `resolveThemeMotion` returns for a theme. */
+export interface ThemeMotion {
+    /** The knobs, defaults filled in. */
+    readonly knobs: ResolvedMotionKnobs;
+    /** Every `--duration-*` token's value. */
+    readonly durations: Readonly<Record<string, string>>;
+    /** `--ease-standard`, `--ease-entrance` and `--ease-move`. */
+    readonly easings: Readonly<Record<string, string>>;
+}
+/**
+ * A theme's motion values, for the animator and for server code (FR6): the
+ * knobs, and the duration and easing tokens they resolve to with the theme's
+ * explicit tokens applied. A token written as a reference (`var(--name)`)
+ * resolves through the theme's tokens, as `resolveThemeTokens` resolves it
+ * (`architecture:theme-tokens` INV6). Pure: it reads only `theme`.
+ */
+export declare function resolveThemeMotion(theme: {
+    readonly motion?: ThemeMotionConfig;
+    readonly __axes?: {
+        readonly motion?: ThemeMotionConfig;
+    };
+    readonly tokens?: Readonly<Record<string, unknown>>;
+    readonly localTokens?: Readonly<Record<string, unknown>>;
+}): ThemeMotion;
+//# sourceMappingURL=themeMotion.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"themeMotion.d.ts","sourceRoot":"","sources":["../../src/theme/themeMotion.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAEH,OAAO,EAAoB,KAAK,iBAAiB,EAAC,MAAM,qBAAqB,CAAC;AAC9E,OAAO,EAGL,KAAK,mBAAmB,EACxB,KAAK,gBAAgB,EACtB,MAAM,eAAe,CAAC;AAIvB,OAAO,EACL,WAAW,EACX,KAAK,eAAe,EACpB,KAAK,mBAAmB,EACxB,KAAK,gBAAgB,EACrB,KAAK,kBAAkB,GACxB,MAAM,eAAe,CAAC;AAEvB;;;GAGG;AACH,MAAM,MAAM,iBAAiB,GAC3B,gBAAgB,GAAG,CAAC,iBAAiB,GAAG,gBAAgB,CAAC,CAAC;AAE5D;;;;GAIG;AACH,eAAO,MAAM,cAAc;;;;CAIgC,CAAC;AAE5D,kEAAkE;AAClE,wBAAgB,kBAAkB,CAChC,MAAM,EAAE,iBAAiB,GAAG,SAAS,GACpC,mBAAmB,CAErB;AAaD;;;;GAIG;AACH,eAAO,MAAM,qBAAqB,2BAA2B,CAAC;AAE9D,0EAA0E;AAC1E,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAMtE;AAED;;;;;;;GAOG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAElD;AAED;;;;;;;GAOG;AACH,wBAAgB,iBAAiB,CAC/B,MAAM,EAAE,iBAAiB,GACxB,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAmCxB;AAED,qDAAqD;AACrD,MAAM,WAAW,WAAW;IAC1B,qCAAqC;IACrC,QAAQ,CAAC,KAAK,EAAE,mBAAmB,CAAC;IACpC,0CAA0C;IAC1C,QAAQ,CAAC,SAAS,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;IACrD,8DAA8D;IAC9D,QAAQ,CAAC,OAAO,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;CACpD;AAED;;;;;;GAMG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,EAAE;IACxC,QAAQ,CAAC,MAAM,CAAC,EAAE,iBAAiB,CAAC;IACpC,QAAQ,CAAC,MAAM,CAAC,EAAE;QAAC,QAAQ,CAAC,MAAM,CAAC,EAAE,iBAAiB,CAAA;KAAC,CAAC;IACxD,QAAQ,CAAC,MAAM,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;IACpD,QAAQ,CAAC,WAAW,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;CAC1D,GAAG,WAAW,CAyCd"}

package/dist/theme/themeMotion.js

@@ -0,0 +1,177 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file themeMotion.ts
+ * @input A theme's motion configuration: the knobs (`tempo`, `character`),
+ *   the existing `MotionScaleConfig`, or both
+ * @output The resolved knobs, the motion tokens they generate, and
+ *   `resolveThemeMotion`, the internal resolver the animator and server code
+ *   read (`spec:AST-108` FR1, FR2, FR5, FR6)
+ * @position Theme utility; consumed by resolveThemeValues.ts. Pure: no DOM,
+ *   no import-time work, safe on the server.
+ *
+ * `tempo` scales every motion duration token, clamped to 0.75–1.5.
+ * `character` picks the entrance and move curves. Every theme follows each
+ * person's Reduce Motion setting (`reducedMotion` resolves to `'system'`).
+ * No spring reads the knobs yet. With the defaults (tempo 1, `'standard'`, `'system'`) every token is
+ * today's.
+ *
+ * A `MotionScaleConfig` keeps generating its duration tokens, and its fields
+ * win over `tempo` (FR5); explicit `tokens` win over both in
+ * resolveThemeValues.
+ *
+ * SYNC: When modified, update:
+ * - /packages/core/src/theme/themeMotion.test.ts
+ * - /packages/core/src/theme/resolveThemeValues.ts
+ * - /packages/core/src/theme/defineTheme.ts (the `motion` field's docs)
+ */
+
+import { expandMotionScale } from "./expandMotionScale.js";
+import { resolveKnobs } from "./motionKnobs.js";
+import { durationDefaults, easeDefaults } from "./tokens.stylex.js";
+import { resolveTokenReferences } from "./tokenReferences.js";
+export { TEMPO_RANGE } from "./motionKnobs.js";
+
+/**
+ * A theme's `motion`: the knobs, the existing `MotionScaleConfig`, or both.
+ * A `MotionScaleConfig`'s fields win over `tempo` for the durations they set.
+ */
+
+/**
+ * The entrance and move curve at each character. `'standard'` is the theme's
+ * `--ease-standard`, so a theme that overrides that easing keeps its entrances
+ * on it.
+ */
+export const CHARACTER_EASE = {
+  crisp: 'cubic-bezier(0, 0, 0.2, 1)',
+  standard: null,
+  expressive: 'cubic-bezier(0.3, 1.2, 0.5, 1)'
+};
+
+/** The knobs of `config`, defaults filled in, `tempo` clamped. */
+export function resolveMotionKnobs(config) {
+  return resolveKnobs(config);
+}
+function isScaleConfig(config) {
+  return 'fast' in config && 'medium' in config && 'ratio' in config;
+}
+
+/** A duration token's value in ms (`'175ms'` → 175). */
+function msOf(value) {
+  return Number.parseFloat(value);
+}
+
+/**
+ * The private custom property a theme with a `tempo` writes beside its
+ * duration tokens: the press release fade (`utils/interactionOverlay.stylex.ts`)
+ * multiplies its clock by it.
+ */
+export const MOTION_TEMPO_PROPERTY = '--_astryx-motion-tempo';
+
+/** The duration tokens at `tempo`: today's values times it, to the ms. */
+export function durationTokensAt(tempo) {
+  const tokens = {};
+  for (const [name, value] of Object.entries(durationDefaults)) {
+    tokens[name] = `${Math.round(msOf(value) * tempo)}ms`;
+  }
+  return tokens;
+}
+
+/**
+ * The private custom property holding a duration token's value before
+ * `tempo` scaled it (`--duration-slow` → `--_astryx-pre-tempo-duration-slow`).
+ * Busy loops (Spinner, Skeleton) read it, falling back to the token, so their
+ * timing follows a duration scale or an explicit token but never `tempo`
+ * (FR4). Private, like every property the knobs add beside the core tokens
+ * (`architecture:theme-tokens` INV1).
+ */
+export function preTempoName(token) {
+  return token.replace(/^--duration-/, '--_astryx-pre-tempo-duration-');
+}
+
+/**
+ * The motion tokens `config` generates (FR2, FR5): `--duration-*` times
+ * `tempo`, with a `MotionScaleConfig`'s own durations winning, and the
+ * job-named `--ease-entrance` and `--ease-move` at the theme's character.
+ * A knob the config leaves out writes nothing, so a theme extending another
+ * keeps the base's value for it; a knob it sets is written even at its
+ * default, so a child can set a base's tempo back to 1.
+ */
+export function expandThemeMotion(config) {
+  const knobs = resolveMotionKnobs(config);
+  const tokens = {};
+  if (knobs.tempoIsSet) {
+    Object.assign(tokens, durationTokensAt(knobs.tempo));
+    for (const [name, value] of Object.entries(durationDefaults)) {
+      tokens[preTempoName(name)] = value;
+    }
+    // The press release fade, a fixed clock in the stylesheet, scales by the
+    // tempo itself (FR4; `component:Button` FR15), read where it plays.
+    tokens[MOTION_TEMPO_PROPERTY] = String(knobs.tempo);
+  }
+  if (isScaleConfig(config)) {
+    const scale = expandMotionScale(config);
+    Object.assign(tokens, scale);
+    if (knobs.tempoIsSet) {
+      for (const [name, value] of Object.entries(scale)) {
+        if (name.startsWith('--duration-')) {
+          tokens[preTempoName(name)] = value;
+        }
+      }
+    }
+  }
+  const scaleEasing = isScaleConfig(config) && config.easing != null ? config.easing : null;
+  const ease = CHARACTER_EASE[knobs.character] ?? (config.character != null ? scaleEasing ?? easeDefaults['--ease-standard'] : scaleEasing);
+  if (ease != null) {
+    tokens['--ease-entrance'] = ease;
+    tokens['--ease-move'] = ease;
+  }
+  return tokens;
+}
+
+/** What `resolveThemeMotion` returns for a theme. */
+
+/**
+ * A theme's motion values, for the animator and for server code (FR6): the
+ * knobs, and the duration and easing tokens they resolve to with the theme's
+ * explicit tokens applied. A token written as a reference (`var(--name)`)
+ * resolves through the theme's tokens, as `resolveThemeTokens` resolves it
+ * (`architecture:theme-tokens` INV6). Pure: it reads only `theme`.
+ */
+export function resolveThemeMotion(theme) {
+  // A defined theme's motion is its axes': its own merged with its base's.
+  const config = theme.__axes?.motion ?? theme.motion;
+  const knobs = resolveMotionKnobs(config);
+  const generated = config ? expandThemeMotion(config) : {};
+  // The graph the references resolve through: the defaults, the knobs'
+  // tokens, then the theme's own (a light/dark pair is not a motion value, so
+  // only plain strings take part).
+  const graph = {
+    ...durationDefaults,
+    ...easeDefaults,
+    ...generated
+  };
+  for (const tokens of [theme.localTokens, theme.tokens]) {
+    for (const [name, value] of Object.entries(tokens ?? {})) {
+      if (typeof value === 'string') {
+        graph[name] = value;
+      }
+    }
+  }
+  const explicit = name => typeof theme.tokens?.[name] === 'string' || name in generated;
+  const resolved = resolveTokenReferences(graph);
+  const durations = {};
+  for (const name of Object.keys(durationDefaults)) {
+    durations[name] = resolved[name];
+  }
+  const standard = resolved['--ease-standard'];
+  return {
+    knobs,
+    durations,
+    easings: {
+      '--ease-standard': standard,
+      '--ease-entrance': explicit('--ease-entrance') ? resolved['--ease-entrance'] : standard,
+      '--ease-move': explicit('--ease-move') ? resolved['--ease-move'] : standard
+    }
+  };
+}

package/dist/theme/tokenReferences.d.ts

@@ -0,0 +1,31 @@
+/**
+ * @file tokenReferences.ts
+ * @input A flat map of token names to raw CSS values
+ * @output `resolveTokenReferences`, which follows `var(--name[, fallback])`
+ *   references through the map, and the CSS parsing helpers it shares
+ *   (`splitTopLevelComma`, `findMatchingParen`)
+ * @position Theme utility with no imports: tokens.ts resolves a theme's token
+ *   graph on it (evaluating color functions as it goes), and themeMotion.ts
+ *   resolves motion tokens written as references on it. Pure; safe on the
+ *   server.
+ *
+ * SYNC: When modified, update:
+ * - /packages/core/src/theme/tokens.ts
+ * - /packages/core/src/theme/themeMotion.ts
+ */
+/**
+ * Split the arguments of a CSS function body on the first top-level comma.
+ * Handles nested functions such as rgba(), color-mix(), var(), and quoted strings.
+ */
+export declare function splitTopLevelComma(input: string): [string, string] | null;
+/** Index of the `)` matching the `(` at `openIndex`, or -1 when unbalanced. */
+export declare function findMatchingParen(input: string, openIndex: number): number;
+/**
+ * Resolves every value in `raw` to a concrete one: each `var(--name[,
+ * fallback])` is replaced by `name`'s resolved value, or by its fallback when
+ * `raw` has no `name`, and is kept as written when neither exists or the
+ * references form a cycle. `evaluate` then runs on each substituted value
+ * (tokens.ts evaluates CSS color functions there).
+ */
+export declare function resolveTokenReferences(raw: Readonly<Record<string, string>>, evaluate?: (expr: string) => string): Record<string, string>;
+//# sourceMappingURL=tokenReferences.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"tokenReferences.d.ts","sourceRoot":"","sources":["../../src/theme/tokenReferences.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;GAcG;AAEH;;;GAGG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,MAAM,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,IAAI,CAwCzE;AAED,+EAA+E;AAC/E,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,MAAM,CAc1E;AAED;;;;;;GAMG;AACH,wBAAgB,sBAAsB,CACpC,GAAG,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,EACrC,QAAQ,GAAE,CAAC,IAAI,EAAE,MAAM,KAAK,MAAqB,GAChD,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAyDxB"}