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

package/src/motion/coast.ts

@@ -29,15 +29,19 @@
 
 import {SETTLE_THRESHOLD, type Animator, type MotionCurve} from './animator';
 import {solveDecay} from './decay';
+import {resolveMotion} from './resolveMotion';
 import {solveSpring, toSpring, type SpringDescription} from './spring';
-import {scroll} from './uikit/scroll';
+import {registerScrollTable, scroll} from './uikit/scroll';
 
 export interface CoastOptions {
   /** Per-millisecond velocity factor; UIScrollView's normal rate by default. */
   rate?: number;
   /** Edges: a coast crossing one hands its velocity to `bounce`. */
   bounds?: Partial<Record<'x' | 'y', {min: number; max: number}>>;
-  /** The edge spring; `scroll.bounce` by default. */
+  /**
+   * The edge spring; `scroll.bounce` by default, which plays its table value
+   * (it is not a motion role: `spec:AST-094` FR4 lists no scroll spring).
+   */
   bounce?: SpringDescription;
   /**
    * The release time on the document timeline (ms, `performance.now()`
@@ -85,7 +89,10 @@ export function coast(
     }
   }
   const rate = options.rate ?? scroll.decelerationRate.normal;
-  const bounce = toSpring(options.bounce ?? scroll.bounce);
+  registerScrollTable();
+  const bounce = toSpring(
+    resolveMotion(animator.element, options.bounce ?? scroll.bounce),
+  );
   const curves: Partial<Record<'x' | 'y', MotionCurve>> = {};
   for (const [key, v0] of Object.entries(velocities) as ['x' | 'y', number][]) {
     const from = animator.get(key, options.at);

package/src/motion/reducedMotion.ts

@@ -45,7 +45,11 @@
  */
 
 import {defaultIsCoarsePointer, defaultPrefersReducedMotion} from './animator';
-import {reducedMotionCrossFade} from './uikit/timing';
+import {resolveMotion} from './resolveMotion';
+import {
+  reducedMotionCrossFade,
+  registerReducedMotionCrossFade,
+} from './uikit/timing';
 
 /** Reduce Motion on a coarse primary pointer: an opacity-only cross-fade. */
 export const REDUCED_MOTION_FADE_QUERY =
@@ -86,7 +90,13 @@ export function reducedMotionFade(
   if (!fades) {
     return {duration: 0, easing: 'linear'};
   }
-  const curve = reducedMotionCrossFade.curve;
+  if (element != null) {
+    registerReducedMotionCrossFade();
+  }
+  const curve =
+    element != null
+      ? resolveMotion(element, reducedMotionCrossFade.curve)
+      : reducedMotionCrossFade.curve;
   return {
     duration: reducedMotionCrossFade.durationMs,
     easing: `cubic-bezier(${curve.join(', ')})`,

package/src/motion/reducedMotionPlan.ts

@@ -80,6 +80,8 @@ export interface ReducedMotionView {
   readonly restingOpacity: number;
   /** Whether a move of an earlier call still waits to land. */
   readonly hasPendingLanding: boolean;
+  /** Whether an earlier dip's fade back in still waits on its landing. */
+  readonly hasWaitingDip: boolean;
 }
 
 /** What Reduce Motion makes of a call. */
@@ -93,6 +95,11 @@ export interface ReducedMotionPlan {
   readonly landing: PlannedLanding | null;
   /** The stylesheet opacity a dip borrowed (no call owns opacity). */
   readonly borrowed?: number | null;
+  /**
+   * The call joins the waiting dip: it names the opacity the dip returns to
+   * and moves nothing, so the fade goes on as it was.
+   */
+  readonly joins?: boolean;
 }
 
 /** The opacity no call has changed. */
@@ -162,7 +169,7 @@ export function planReducedMotion(
   // A move still waiting to land (an earlier dip's) lands at this call's
   // invisible moment, never while the element shows.
   const pending = view.hasPendingLanding;
-  // Not a theme role: no theme lengthens it (design:reduced-motion DR4).
+  // Not a role: nothing lengthens it (design:reduced-motion DR4).
   const ms = reducedMotionCrossFade.durationMs;
   const landsLater = (
     at: number,
@@ -183,6 +190,18 @@ export function planReducedMotion(
         : {}),
     };
   };
+  // A call that names the opacity a waiting dip returns to, and names no
+  // travel, joins that dip: the fade goes on as it was and the call settles
+  // when the dip ends. A second dip, opened from where the first had got
+  // to, would fade the element out twice.
+  if (
+    named &&
+    view.hasWaitingDip &&
+    !properties.some(property => TRAVEL_PROPERTIES.includes(property)) &&
+    Math.abs(opacityTo - view.opacityHeading()) < 1e-6
+  ) {
+    return {atOnce: [], opacityFade: null, holds, landing: null, joins: true};
+  }
   // Travel lands only while the element is transparent (DR1, DR2): an
   // entrance that starts visible, or an exit that ends visible, dips instead
   // when it has travel or a waiting landing to carry.

package/src/motion/resolveMotion.ts

@@ -0,0 +1,68 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file resolveMotion.ts
+ * @input A motion role: a spring or curve of a registered motion table, or a
+ *   table group and the key of one of its values
+ * @output resolveMotion: the role's value
+ * @position Motion foundation; the animator resolves every spring and curve
+ *   it is handed with it, and components resolve the durations they time
+ *   with it
+ *
+ * Every touch motion passes through here, so the role a value plays is named
+ * in one place. A role plays its table value: the per-role tables stay
+ * internal (`spec:AST-094` DEC-15), so nothing reads a role's CSS variable
+ * and no page or theme style sets a role. Nothing here reads style or
+ * layout, listens or observes, imports a table, or runs on import or on the
+ * server.
+ *
+ * SYNC: When modified, update:
+ * - /packages/core/src/motion/resolveMotion.test.ts
+ * - /packages/core/src/motion/animator.ts (resolves each role it plays)
+ */
+
+import type {MotionCurvePoints} from './roles';
+import type {SpringDescription} from './spring';
+
+/**
+ * A motion role's value: its table value, as the per-role tables stay
+ * internal (`spec:AST-094` DEC-15). Hand it a spring or curve of a motion
+ * table, or a table group and a key (the way to name a duration, which is a
+ * bare number):
+ *
+ * @example
+ * ```
+ * const spring = resolveMotion(sheet, springs.settle);
+ * const fadeMs = resolveMotion(row, timing, 'stateChangeMs');
+ * ```
+ *
+ * The element names where the motion plays; anything that is not a role
+ * comes back unchanged too, so a spring
+ * written inline at a call site keeps working.
+ */
+export function resolveMotion<T extends SpringDescription>(
+  element: Element | null | undefined,
+  spring: T,
+): T | SpringDescription;
+export function resolveMotion(
+  element: Element | null | undefined,
+  curve: MotionCurvePoints,
+): MotionCurvePoints;
+export function resolveMotion<G extends object, K extends keyof G & string>(
+  element: Element | null | undefined,
+  group: G,
+  key: K,
+): G[K] extends number
+  ? number
+  : G[K] extends MotionCurvePoints
+    ? MotionCurvePoints
+    : G[K] | SpringDescription;
+export function resolveMotion(
+  _element: Element | null | undefined,
+  leafOrGroup: object,
+  key?: string,
+): unknown {
+  return key === undefined
+    ? leafOrGroup
+    : (leafOrGroup as Record<string, unknown>)[key];
+}

package/src/motion/roleValue.ts

@@ -69,7 +69,8 @@ export function short(n: number): string {
  *   spring: mass folds into the duration, overdamping into a negative bounce);
  * - duration: `250ms`;
  * - curve: `cubic-bezier(0.42, 0, 0.58, 1)`, usable as is in CSS.
- * Throws on a value that is not a valid value of its kind.
+ * Throws on a value that is not a valid value of its kind, a spring that
+ * never settles included.
  */
 export function formatMotionRoleValue(
   kind: MotionRoleKind,

package/src/motion/uikit/timing.ts

@@ -96,7 +96,7 @@ export const reducedMotionCrossFade = {
    * becomes an opacity-only cross-fade of this length on a coarse pointer
    * (design:reduced-motion DR2 caps it at 200 ms, by owner decision DEC-1
    * of 2026-10-24, departing from UIKit's own navigation cross-fade,
-   * measured below at 0.5 s). Not a theme role: no theme lengthens it (DR4).
+   * measured below at 0.5 s). Not a role: nothing lengthens it (DR4).
    * @source apple-docs https://developer.apple.com/documentation/uikit/uiaccessibility/preferscrossfadetransitions
    *   (the setting)
    * @source measured: UIKit lab (injected host app), iOS 26.2 simulator,
@@ -208,3 +208,17 @@ export function registerTimingTable(): void {
     ],
   });
 }
+
+// The fade's curve under its table path, for registerReducedMotionCrossFade.
+const reducedMotionCrossFadeRoles = {curves: {move}};
+
+/**
+ * Registers only the Reduce Motion fade's curve as its role,
+ * `timing.curves.move`, for code that reads the fade without the rest of the
+ * table (the animator, reducedMotionFade()). The fade's length is not a role.
+ */
+export function registerReducedMotionCrossFade(): void {
+  registerMotionTable('timing', reducedMotionCrossFadeRoles, {
+    roles: ['curves.move'],
+  });
+}

package/src/theme/Theme.doc.mjs

@@ -69,7 +69,7 @@ export const docs = {
       type: 'DefinedTheme',
       required: true,
       description:
-        'Theme object to apply. Prefer built theme objects for static production themes; use runtime `defineTheme()` for dynamic themes.',
+        "Theme object to apply. Prefer built theme objects for static production themes; use runtime `defineTheme()` for dynamic themes. Its `motion` can set `tempo` (0.75–1.5) and `character` (`'crisp' | 'standard' | 'expressive'`).",
     },
     {
       name: 'mode',

package/src/theme/defineTheme.ts

@@ -118,6 +118,7 @@ import {
   typeScaleDefaults,
 } from './tokens.stylex';
 import type {MotionScaleConfig} from './expandMotionScale';
+import type {ThemeMotionConfig} from './themeMotion';
 import type {RadiusScaleConfig} from './expandRadiusScale';
 import type {ColorScaleConfig} from './expandColorScale';
 import {resolveThemeValues, type ThemeValuesInput} from './resolveThemeValues';
@@ -132,7 +133,7 @@ import {
 } from './themeAdaptations';
 
 import type {DomainTokenName} from './domainTokens';
-import {domainTokenDefaults} from './domainTokens';
+import {domainTokenDefaults} from './domainTokens/domainTokenDefaults';
 import type {SyntaxThemeDefinition} from './syntax';
 import {registerTheme} from './themeRegistry';
 import {resolveLocalTokenContract} from './localTokens';
@@ -290,13 +291,27 @@ export interface DefineThemeInput<
    */
   typography?: TypographyConfig;
   /**
-   * Motion configuration. Computes duration min/max variants from
-   * base values and a scaling ratio: min = base × ratio, max = base / ratio.
+   * Motion configuration: two knobs (spec:AST-108), a motion scale, or both.
    *
-   * Explicit `tokens` overrides take precedence over motion-generated values.
+   * - `tempo` (default 1, clamped to 0.75–1.5) scales every motion duration
+   *   token; touch motion's springs don't read it yet.
+   * - `character` (`'crisp'`, `'standard'` or `'expressive'`) sets the
+   *   entrance and move curves; exits and fades never overshoot.
+   *
+   * Every theme follows each person's Reduce Motion setting; nothing loosens it.
+   *
+   * A motion scale computes duration min/max variants from base values and a
+   * ratio (min = base × ratio, max = base / ratio); its durations win over
+   * `tempo`, and explicit `tokens` overrides win over both. Finger tracking,
+   * momentum, the keyboard, hover, the press's onset delay and tap flash, and
+   * busy loops never follow the knobs; the press release fade follows
+   * `tempo`.
    *
    * @example
    * ```
+   * motion: { tempo: 1.2, character: 'crisp' }
+   *
+   * // A motion scale, as before:
    * motion: { fast: 175, medium: 410, slow: 975, ratio: 0.75 }
    *
    * // Suggested starting points:
@@ -305,7 +320,7 @@ export interface DefineThemeInput<
    * //   Cinematic: { fast: 200, medium: 500, slow: 1200, ratio: 0.7 }
    * ```
    */
-  motion?: MotionScaleConfig;
+  motion?: ThemeMotionConfig;
   /**
    * Radius configuration. Generates radius token overrides
    * from a base unit and multiplier.
@@ -648,6 +663,73 @@ function describeBadBase(value: unknown): string {
   return `an object with keys [${keys.slice(0, 4).join(', ')}${keys.length > 4 ? ', …' : ''}]`;
 }
 
+/** The slow band's duration tokens. */
+const SLOW_BAND = [
+  '--duration-slow-min',
+  '--duration-slow',
+  '--duration-slow-max',
+] as const;
+
+/**
+ * The base's tokens for the duration-scale fields a child leaves unset
+ * (spec:AST-108 FR5, field by field): a child that sets no `slow` of its own
+ * regenerates only the fast and medium bands, so an inherited slow band stays
+ * as the base's tokens hold it, at the ratio it was made with; and a child
+ * that sets no `easing` keeps the base's `--ease-standard`, an explicit one
+ * included, however many themes down either is inherited.
+ */
+function inheritedScaleTokens(
+  base: DefinedTheme,
+  baseMotion: ThemeMotionConfig,
+  own: ThemeMotionConfig,
+): Partial<Record<string, TokenValue>> | undefined {
+  const names = [
+    ...('slow' in baseMotion && !('slow' in own) ? SLOW_BAND : []),
+    ...('easing' in baseMotion && !('easing' in own)
+      ? (['--ease-standard'] as const)
+      : []),
+  ];
+  if (names.length === 0) {
+    return undefined;
+  }
+  const tokens = base.tokens as Record<string, string | undefined>;
+  return Object.fromEntries(
+    names.flatMap(name =>
+      tokens[name] !== undefined ? [[name, tokens[name]]] : [],
+    ),
+  );
+}
+
+/**
+ * Refuses a duration scale that is missing `fast`, `medium` or `ratio` after
+ * inheritance. The scale applies only when all three are present, so a partial
+ * one beside a knob (`{fast: 100, tempo: 1.2}`) would otherwise be dropped
+ * silently, though its fields win over `tempo` (spec:AST-108 FR5). Adaptation
+ * rules refuse the same in `completeMotion`.
+ */
+function assertCompleteMotionScale(
+  motion: ThemeMotionConfig,
+  themeName: string,
+): void {
+  const scale = motion as Partial<MotionScaleConfig>;
+  const writesScale =
+    scale.fast !== undefined ||
+    scale.medium !== undefined ||
+    scale.ratio !== undefined ||
+    scale.slow !== undefined ||
+    scale.easing !== undefined;
+  if (
+    writesScale &&
+    (scale.fast === undefined ||
+      scale.medium === undefined ||
+      scale.ratio === undefined)
+  ) {
+    throw new Error(
+      `defineTheme("${themeName}"): \`motion\` sets a duration scale field, so it must supply \`fast\`, \`medium\`, and \`ratio\` unless each missing field is inherited from \`extends\`.`,
+    );
+  }
+}
+
 /**
  * Create an Astryx theme.
  *
@@ -682,13 +764,36 @@ export function defineTheme<
   // The theme's own value axes and the resolved base an `extends` supplies.
   // The same axis metadata is retained so adaptation rules can complete partial
   // configs without approximating values from unrelated built-in defaults.
+  //
+  // Motion inherits field by field (spec:AST-108 FR5): a duration-scale field
+  // or knob the child leaves unset keeps its base's value, so the child's
+  // motion tokens come from the merged configuration. They resolve base first,
+  // then generated (`architecture:theme-authoring-contract`): what the child
+  // generates replaces the base's tokens, its explicit ones included. A
+  // child's motion regenerates only what it sets: an inherited slow band and
+  // an inherited easing keep the base's tokens.
+  const baseMotion = base?.__axes?.motion;
+  const motion: ThemeMotionConfig | undefined =
+    input.motion != null && baseMotion != null
+      ? {...baseMotion, ...input.motion}
+      : input.motion;
+  if (motion != null) {
+    assertCompleteMotionScale(motion, input.name);
+  }
+  const inheritedScale =
+    input.motion != null && base != null && baseMotion != null
+      ? inheritedScaleTokens(base, baseMotion, input.motion)
+      : undefined;
   const ownValues: ThemeValuesInput = {
     typography: input.typography,
     color: input.color,
     radius: input.radius,
-    motion: input.motion,
+    motion,
     syntax: input.syntax,
-    tokens: input.tokens,
+    tokens:
+      inheritedScale != null && Object.keys(inheritedScale).length > 0
+        ? {...inheritedScale, ...input.tokens}
+        : input.tokens,
     components: input.components,
   };
   const ownAxes: ThemeGenerativeAxes = {
@@ -701,7 +806,11 @@ export function defineTheme<
     ? {tokens: base.tokens, components: base.components}
     : undefined;
 
-  const {tokens, components} = resolveThemeValues(ownValues, seed);
+  // An explicit --ease-standard follows the character the theme inherits
+  // when it sets no motion of its own (FR2).
+  const {tokens, components} = resolveThemeValues(ownValues, seed, {
+    inheritedCharacter: baseMotion?.character,
+  });
 
   // On-media token overrides (base's resolved surface, then defaults, then
   // this theme's own overrides). They compile after adaptations so the

package/src/theme/domainTokens/domainTokenDefaults.ts

@@ -0,0 +1,19 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file domainTokens/domainTokenDefaults.ts
+ * @input syntaxTokenDefaults, dataTokenDefaults
+ * @output domainTokenDefaults
+ * @position Merges the domain token defaults for defineTheme. Kept out of the
+ *   domainTokens barrel because defineTheme sits in a lazily imported module
+ *   graph, which imports no barrel (pinned by scripts/core-single-bundle.test.mjs).
+ */
+
+import {syntaxTokenDefaults} from '../syntax/tokens';
+import {dataTokenDefaults} from './dataTokens';
+
+/** All domain token defaults merged — used by defineTheme for validation */
+export const domainTokenDefaults: Record<string, string> = {
+  ...syntaxTokenDefaults,
+  ...dataTokenDefaults,
+};

package/src/theme/domainTokens/index.ts

@@ -6,8 +6,10 @@
  * @output domainTokenDefaults, DomainTokenName
  * @position Token aggregator; consumed by defineTheme for validation + autocomplete
  *
- * Merges all domain token defaults into a single map for defineTheme.
- * Actual token definitions live in their own directories (syntax/, dataviz/).
+ * Re-exports only. The merged map lives in domainTokenDefaults.ts so that
+ * defineTheme, inside a lazily imported module graph, imports it without a
+ * barrel. Actual token definitions live in their own directories (syntax/,
+ * dataviz/).
  */
 
 export {syntaxTokenDefaults} from '../syntax/tokens';
@@ -16,16 +18,10 @@ export type {SyntaxTokenName} from '../syntax/tokens';
 export {dataTokenDefaults} from './dataTokens';
 export type {DataTokenName} from './dataTokens';
 
-import {syntaxTokenDefaults} from '../syntax/tokens';
-import {dataTokenDefaults} from './dataTokens';
+export {domainTokenDefaults} from './domainTokenDefaults';
+
 import type {SyntaxTokenName} from '../syntax/tokens';
 import type {DataTokenName} from './dataTokens';
 
-/** All domain token defaults merged — used by defineTheme for validation */
-export const domainTokenDefaults: Record<string, string> = {
-  ...syntaxTokenDefaults,
-  ...dataTokenDefaults,
-};
-
 /** Union of all domain token names */
 export type DomainTokenName = SyntaxTokenName | DataTokenName;

package/src/theme/index.ts

@@ -104,6 +104,11 @@ export type {ColorScaleConfig, ColorScaleTokens} from './expandColorScale';
 
 export {expandMotionScale} from './expandMotionScale';
 export type {MotionScaleConfig, MotionScaleTokens} from './expandMotionScale';
+export type {
+  MotionCharacter,
+  ThemeMotionConfig,
+  ThemeMotionKnobs,
+} from './themeMotion';
 
 // Export token defaults and vars for use in custom components and themes
 export {

package/src/theme/motionKnobs.ts

@@ -0,0 +1,82 @@
+// 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. */
+export type MotionCharacter = 'crisp' | 'standard' | 'expressive';
+
+/**
+ * Whose Reduce Motion setting a theme follows: `'system'`, each person's own.
+ * Internal: no theme sets it until `'always'` ships (`spec:AST-108` FR6).
+ */
+export type ThemeReducedMotion = 'system';
+
+/** The motion knobs a theme sets (`spec:AST-108` FR1). */
+export interface ThemeMotionKnobs {
+  /**
+   * Scales every motion duration: 1 is Astryx's own, 0.75 the quickest and
+   * 1.5 the slowest (values outside are clamped). Default 1.
+   */
+  tempo?: number;
+  /**
+   * `'crisp'` decelerates without overshoot, `'standard'` is Astryx's own,
+   * `'expressive'` overshoots slightly on entrances and moves. Exits and
+   * fades never overshoot. Default `'standard'`.
+   */
+  character?: MotionCharacter;
+}
+
+/** The knobs with their defaults filled in and `tempo` clamped. */
+export interface ResolvedMotionKnobs {
+  readonly tempo: number;
+  readonly character: MotionCharacter;
+  readonly reducedMotion: ThemeReducedMotion;
+  /**
+   * Whether the theme sets `tempo` itself. A `MotionScaleConfig` alone
+   * implies a tempo for its CSS durations only; the animator's springs stay
+   * at tempo 1 unless this is true (FR5).
+   */
+  readonly tempoIsSet: boolean;
+}
+
+/** The range `tempo` is clamped to. */
+export const TEMPO_RANGE = {min: 0.75, max: 1.5} as const;
+
+const CHARACTERS: ReadonlyArray<MotionCharacter> = [
+  'crisp',
+  'standard',
+  'expressive',
+];
+
+/** The knobs of `config`, defaults filled in, `tempo` clamped. */
+export function resolveKnobs(
+  config: ThemeMotionKnobs | undefined,
+): ResolvedMotionKnobs {
+  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 as number),
+      )
+    : 1;
+  const character =
+    config?.character != null && CHARACTERS.includes(config.character)
+      ? config.character
+      : 'standard';
+  return {tempo, character, reducedMotion: 'system', tempoIsSet};
+}

package/src/theme/resolveThemeValues.ts

@@ -31,8 +31,14 @@ import {
   generateTypeScaleComponents,
   type TypeScaleConfig,
 } from './expandTypeScale';
-import {expandMotionScale, type MotionScaleConfig} from './expandMotionScale';
+import {
+  expandThemeMotion,
+  preTempoName,
+  type MotionCharacter,
+  type ThemeMotionConfig,
+} from './themeMotion';
 import {expandRadiusScale, type RadiusScaleConfig} from './expandRadiusScale';
+import {easeDefaults} from './tokens.stylex';
 import {expandColorScale, type ColorScaleConfig} from './expandColorScale';
 import {deepMergeComponents} from './mergeComponents';
 
@@ -54,8 +60,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. */
@@ -271,7 +277,20 @@ export function buildFontFamilyTokens(
 export function resolveThemeValues(
   input: ThemeValuesInput,
   seed?: ThemeValuesSeed,
-  {strictTokens = false}: {strictTokens?: boolean} = {},
+  {
+    strictTokens = false,
+    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 {
   const tokens: Record<string, string> = {...seed?.tokens};
 
@@ -293,9 +312,19 @@ export function resolveThemeValues(
     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
@@ -314,9 +343,42 @@ export function resolveThemeValues(
   // 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 as Partial<Record<string, TokenValue>>;
     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: Partial<Record<string, TokenValue>> = 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;
       }
     }
   }