clava 0.3.0 → 0.4.1

package/src/index.ts

@@ -5,14 +5,13 @@ import type {
   ClassValue,
   ComponentProps,
   ComponentResult,
-  Computed,
-  ComputedVariants,
   ExtendableVariants,
   HTMLObjProps,
   HTMLProps,
   JSXProps,
   MergeVariants,
   ModalComponent,
+  Refine,
   SplitPropsFunction,
   StyleClassProps,
   StyleClassValue,
@@ -42,33 +41,33 @@ type ComputeFn = (
   skipValues: Record<string, Set<string>> | null,
   classesOut: ClsxClassValue[],
   styleOut: StyleValue,
-  runState?: ComputedRunState,
+  runState?: RefineRunState,
   protectedVariants?: Record<string, unknown> | null,
   pendingProtectedVariants?: Record<string, unknown> | null,
   protectedVariantKeys?: Set<string> | null,
 ) => Record<string, unknown>;
 
-type ResolveComputedFn = (
+type ResolveRefineFn = (
   resolved: Record<string, unknown>,
   userVariantProps: Record<string, unknown>,
   filterOwnVariants?: boolean,
-  runState?: ComputedRunState,
+  runState?: RefineRunState,
   protectedVariants?: Record<string, unknown> | null,
   pendingProtectedVariants?: Record<string, unknown> | null,
   protectedVariantKeys?: Set<string> | null,
 ) => Record<string, unknown>;
 
-interface ComputedRunState {
+interface RefineRunState {
   remaining: number;
-  warned: boolean;
+  warned?: boolean;
 }
 
 // Internal metadata stored on components but hidden from public types.
 interface ComponentMeta {
   baseClass: string;
   staticDefaults: Record<string, unknown>;
-  // Returns variants set via setDefaultVariants in the computed function chain.
-  // null when this component has no resolveDefaults work to do (no `computed`
+  // Returns variants set via setDefaultVariants in the refine function chain.
+  // null when this component has no resolveDefaults work to do (no `refine`
   // and no extends with work).
   resolveDefaults:
     | ((
@@ -79,22 +78,39 @@ interface ComponentMeta {
   // Returns variant classes + style for this component, used by extending
   // components. Top-level rendering also routes through this.
   compute: ComputeFn;
-  resolveComputed: ResolveComputedFn | null;
+  resolveRefine: ResolveRefineFn | null;
   // Reference identity is used to detect mixed-factory `extend`. When a
   // component is extended by a parent from a different `create()` call, the
   // parent applies this transform to the extend's contribution before joining,
   // preserving each factory's transform boundary.
   transformClass: (className: string) => string;
+  // Variant keys whose effective definition in this component's chain is a
+  // function. An extending component that supplies a non-function variant for
+  // the same key uses this to tell us to skip that key (matching the
+  // type-level "function variant is replaced by anything in the child" rule).
+  // Empty when no key in this chain is a function variant.
+  functionVariantKeys: Set<string>;
 }
 
 const META_KEY = "__meta";
 
+interface ComponentWithMeta {
+  [META_KEY]?: ComponentMeta;
+}
+
 const EMPTY_DEFAULTS: Record<string, unknown> = Object.freeze({}) as Record<
   string,
   unknown
 >;
 
-const MAX_COMPUTED_RUNS = 50;
+const MAX_REFINE_RUNS = 50;
+
+// Once a refine loop is within this many iterations of the cap, start tracking
+// every variant key that changes between iterations so the warning can report
+// every key that contributed to the oscillation, not just the keys that
+// happened to flip on the final step. Convergent loops (the common case) exit
+// well before this threshold and pay no per-iteration tracking cost.
+const REFINE_UNSTABLE_TRACKING_WINDOW = 10;
 
 function areVariantsEqual(
   a: Record<string, unknown>,
@@ -111,16 +127,94 @@ function areVariantsEqual(
   return true;
 }
 
-function warnComputedLimit(runState: ComputedRunState): void {
+interface CreationFrame {
+  stack?: string;
+}
+
+// Captures the call site of the function passed in `skipFn` so refine-limit
+// warnings can point developers at the originating `cv()` call. Returns
+// `undefined` in production so bundlers that replace `process.env.NODE_ENV` at
+// build time can drop the entire warning machinery. The underlying `.stack`
+// string is formatted lazily on first access in every major engine (V8,
+// SpiderMonkey, JavaScriptCore), so holding the captured frame for the
+// lifetime of the component is cheap when no warning fires.
+function captureCreationFrame(skipFn: Function): CreationFrame | undefined {
+  if (process.env.NODE_ENV === "production") return undefined;
+  if (typeof Error.captureStackTrace === "function") {
+    const holder: CreationFrame = {};
+    Error.captureStackTrace(holder, skipFn);
+    return holder;
+  }
+  // Engines without `Error.captureStackTrace` (SpiderMonkey, JavaScriptCore)
+  // can't strip internal frames, but their `Error.stack` getter is still
+  // lazy, so returning the Error instance defers the format cost. The
+  // resulting trace includes 1–2 extra frames at the top from this helper and
+  // `cv` itself.
+  return new Error();
+}
+
+function formatCreationStack(frame: CreationFrame): string | undefined {
+  let stack = frame.stack;
+  if (!stack) return undefined;
+  // V8 prefixes the stack with a leading "Error" / "Error: message" line that
+  // isn't meaningful for a captured location — drop it.
+  const newlineIdx = stack.indexOf("\n");
+  if (newlineIdx > 0) {
+    const firstLine = stack.slice(0, newlineIdx);
+    if (firstLine === "Error" || firstLine.startsWith("Error:")) {
+      stack = stack.slice(newlineIdx + 1);
+    }
+  }
+  return stack;
+}
+
+// Accumulates the union of variant keys that differ between `prev` and `next`
+// into `into`. Called on every non-converging iteration of the refine loop so
+// the refine-limit warning can report any key that ever changed across runs,
+// not just the keys that changed on the final iteration (two keys flipping at
+// different cadences could otherwise hide each other on the last step).
+function accumulateUnstableVariantKeys(
+  into: Set<string>,
+  prev: Record<string, unknown>,
+  next: Record<string, unknown>,
+): void {
+  for (const key in next) {
+    if (!Object.hasOwn(next, key)) continue;
+    if (!Object.is(prev[key], next[key])) {
+      into.add(key);
+    }
+  }
+  for (const key in prev) {
+    if (!Object.hasOwn(prev, key)) continue;
+    if (Object.hasOwn(next, key)) continue;
+    into.add(key);
+  }
+}
+
+function warnRefineLimit(
+  runState: RefineRunState,
+  creationFrame: CreationFrame | undefined,
+  unstableKeys: Set<string> | null,
+): void {
+  // Bundlers are expected to replace this branch with a production literal,
+  // allowing warning-only code below to be removed from consumer bundles.
+  if (process.env.NODE_ENV === "production") return;
   if (runState.warned) return;
   runState.warned = true;
-  if (process.env.NODE_ENV !== "production") {
-    console.warn(
-      "Clava: Maximum computed update iterations exceeded. This can happen " +
-        "when a computed callback calls setVariants or setDefaultVariants, " +
-        "but one of the variants changes on every run.",
-    );
+  let message =
+    "Clava: Maximum refine iterations exceeded. This can happen when a " +
+    "refine callback calls setVariants or setDefaultVariants, but one " +
+    "of the variants changes on every run.";
+  if (unstableKeys && unstableKeys.size > 0) {
+    message += `\nVariant(s) that did not stabilize: ${Array.from(unstableKeys).join(", ")}.`;
   }
+  if (creationFrame) {
+    const creationStack = formatCreationStack(creationFrame);
+    if (creationStack) {
+      message += `\nComponent created at:\n${creationStack}`;
+    }
+  }
+  console.warn(message);
 }
 
 function getExtUserVariantProps(
@@ -149,7 +243,9 @@ function mergeVariants(
     for (const key in source) {
       if (!Object.hasOwn(source, key)) continue;
       const value = source[key];
-      if (!Object.is(target[key], value)) changed = true;
+      if (!Object.is(target[key], value)) {
+        changed = true;
+      }
       target[key] = value;
     }
     return changed;
@@ -158,21 +254,22 @@ function mergeVariants(
     if (!Object.hasOwn(source, key)) continue;
     if (skipKeys.has(key)) continue;
     const value = source[key];
-    if (!Object.is(target[key], value)) changed = true;
+    if (!Object.is(target[key], value)) {
+      changed = true;
+    }
     target[key] = value;
   }
   return changed;
 }
 
-// Dynamic property access on function requires cast through unknown.
+// Components carry internal metadata on a non-public property so user-facing
+// component types stay clean.
 function getComponentMeta(component: AnyComponent): ComponentMeta | undefined {
-  return (component as unknown as Record<string, unknown>)[META_KEY] as
-    | ComponentMeta
-    | undefined;
+  return (component as AnyComponent & ComponentWithMeta)[META_KEY];
 }
 
 function setComponentMeta(component: AnyComponent, meta: ComponentMeta): void {
-  (component as unknown as Record<string, unknown>)[META_KEY] = meta;
+  (component as AnyComponent & ComponentWithMeta)[META_KEY] = meta;
 }
 
 export type {
@@ -202,16 +299,14 @@ export type Variant<
 
 export interface CVConfig<
   V extends Variants = {},
-  CV extends ComputedVariants = {},
   E extends AnyComponent[] = [],
 > {
   extend?: E;
   class?: ClassValue;
   style?: StyleValue;
   variants?: ExtendableVariants<V, E>;
-  computedVariants?: CV;
-  defaultVariants?: VariantValues<MergeVariants<V, CV, E>>;
-  computed?: Computed<MergeVariants<V, CV, E>>;
+  defaultVariants?: VariantValues<MergeVariants<V, E>>;
+  refine?: Refine<MergeVariants<V, E>>;
 }
 
 interface CreateParams {
@@ -282,7 +377,7 @@ function extractClassAndStylePrebuilt(value: unknown): PrebuiltValue {
  * components.
  */
 function collectVariantKeys(
-  config: CVConfig<Variants, ComputedVariants, AnyComponent[]>,
+  config: CVConfig<Variants, AnyComponent[]>,
 ): string[] {
   const keys = new Set<string>();
 
@@ -307,32 +402,31 @@ function collectVariantKeys(
     }
   }
 
-  if (config.computedVariants) {
-    for (const key in config.computedVariants) {
-      if (!Object.hasOwn(config.computedVariants, key)) continue;
-      keys.add(key);
-    }
-  }
-
   return Array.from(keys);
 }
 
 function isVariantDisabled(
-  config: CVConfig<Variants, ComputedVariants, AnyComponent[]>,
+  config: CVConfig<Variants, AnyComponent[]>,
   key: string,
 ): boolean {
   return config.variants?.[key] === null;
 }
 
 function getVariantValueKey(value: unknown): string | undefined {
-  if (typeof value === "string") return value;
-  if (typeof value === "number") return String(value);
-  if (typeof value === "boolean") return String(value);
+  if (typeof value === "string") {
+    return value;
+  }
+  if (typeof value === "number") {
+    return String(value);
+  }
+  if (typeof value === "boolean") {
+    return String(value);
+  }
   return undefined;
 }
 
 function isVariantValueDisabled(
-  config: CVConfig<Variants, ComputedVariants, AnyComponent[]>,
+  config: CVConfig<Variants, AnyComponent[]>,
   key: string,
   value: unknown,
 ): boolean {
@@ -344,10 +438,12 @@ function isVariantValueDisabled(
 }
 
 function collectDisabledVariantKeys(
-  config: CVConfig<Variants, ComputedVariants, AnyComponent[]>,
+  config: CVConfig<Variants, AnyComponent[]>,
 ): Set<string> {
   const keys = new Set<string>();
-  if (!config.variants) return keys;
+  if (!config.variants) {
+    return keys;
+  }
   for (const key in config.variants) {
     if (!Object.hasOwn(config.variants, key)) continue;
     if ((config.variants as Record<string, unknown>)[key] === null) {
@@ -358,10 +454,12 @@ function collectDisabledVariantKeys(
 }
 
 function collectDisabledVariantValues(
-  config: CVConfig<Variants, ComputedVariants, AnyComponent[]>,
+  config: CVConfig<Variants, AnyComponent[]>,
 ): Record<string, Set<string>> {
   const values: Record<string, Set<string>> = {};
-  if (!config.variants) return values;
+  if (!config.variants) {
+    return values;
+  }
   for (const key in config.variants) {
     if (!Object.hasOwn(config.variants, key)) continue;
     const variant = (config.variants as Record<string, unknown>)[key];
@@ -401,14 +499,22 @@ function normalizeKeySource(source: unknown): NormalizedSource {
     };
   }
 
-  if (!source) return EMPTY_SOURCE;
+  if (!source) {
+    return EMPTY_SOURCE;
+  }
   if (typeof source !== "object" && typeof source !== "function") {
     return EMPTY_SOURCE;
   }
   const typed = source as Record<string, unknown>;
-  if (typeof typed.getVariants !== "function") return EMPTY_SOURCE;
-  if (!Array.isArray(typed.propKeys)) return EMPTY_SOURCE;
-  if (!Array.isArray(typed.variantKeys)) return EMPTY_SOURCE;
+  if (typeof typed.getVariants !== "function") {
+    return EMPTY_SOURCE;
+  }
+  if (!Array.isArray(typed.propKeys)) {
+    return EMPTY_SOURCE;
+  }
+  if (!Array.isArray(typed.variantKeys)) {
+    return EMPTY_SOURCE;
+  }
 
   return {
     propKeys: typed.propKeys as string[],
@@ -544,7 +650,9 @@ function buildPrebuiltVariant(variantDef: unknown): PrebuiltVariant {
     if (!Object.hasOwn(variantDef, key)) continue;
     const value = variantDef[key];
     if (value === null) {
-      if (!disabledValues) disabledValues = new Set<string>();
+      if (!disabledValues) {
+        disabledValues = new Set<string>();
+      }
       disabledValues.add(key);
       continue;
     }
@@ -565,14 +673,10 @@ export function create({
 }: CreateParams = {}) {
   const cx = (...classes: ClsxClassValue[]) => transformClass(clsx(...classes));
 
-  const cv = <
-    V extends Variants = {},
-    CV extends ComputedVariants = {},
-    const E extends AnyComponent[] = [],
-  >(
-    config: CVConfig<V, CV, E> = {},
-  ): CVComponent<V, CV, E> => {
-    type MergedVariants = MergeVariants<V, CV, E>;
+  const cv = <V extends Variants = {}, const E extends AnyComponent[] = []>(
+    config: CVConfig<V, E> = {},
+  ): CVComponent<V, E> => {
+    type MergedVariants = MergeVariants<V, E>;
 
     // ----- Pre-computed at creation time -----
     const variantKeys = collectVariantKeys(config);
@@ -589,41 +693,34 @@ export function create({
     const extend = config.extend;
     const hasExtend = !!extend && extend.length > 0;
     const variants = config.variants;
-    const computedVariantsCfg = config.computedVariants;
-    const computed = config.computed;
+    const refine = config.refine;
     const baseStyle = config.style;
     const hasBaseStyle = !!baseStyle;
 
-    // Pre-build variant entries for fast iteration. For each variant key in
-    // `variants`, we have a name and a PrebuiltVariant with normalized values.
+    // Split `variants` entries into static entries (object/shorthand) and
+    // function-variant entries. Static entries are pre-built into
+    // PrebuiltVariant for fast iteration. Function-variant entries override
+    // any same-key inherited variant (see `staticExtSkipKeys`).
     const variantEntryNames: string[] = [];
     const variantEntryDefs: PrebuiltVariant[] = [];
+    const functionVariantNames: string[] = [];
+    const functionVariantFns: Array<(value: unknown) => unknown> = [];
     if (variants) {
       for (const name in variants) {
         if (!Object.hasOwn(variants, name)) continue;
         const variant = (variants as Record<string, unknown>)[name];
         if (variant === null) continue;
+        if (typeof variant === "function") {
+          functionVariantNames.push(name);
+          functionVariantFns.push(variant as (value: unknown) => unknown);
+          continue;
+        }
         variantEntryNames.push(name);
         variantEntryDefs.push(buildPrebuiltVariant(variant));
       }
     }
     const variantEntryCount = variantEntryNames.length;
-
-    // Pre-built computed-variants entries.
-    const computedVariantNames: string[] = [];
-    const computedVariantFns: Array<(value: unknown) => unknown> = [];
-    if (computedVariantsCfg) {
-      for (const name in computedVariantsCfg) {
-        if (!Object.hasOwn(computedVariantsCfg, name)) continue;
-        computedVariantNames.push(name);
-        computedVariantFns.push(
-          (computedVariantsCfg as Record<string, (value: unknown) => unknown>)[
-            name
-          ] as (value: unknown) => unknown,
-        );
-      }
-    }
-    const computedVariantCount = computedVariantNames.length;
+    const functionVariantCount = functionVariantNames.length;
 
     // Pre-compute static defaults. Includes:
     // - extended components' static defaults
@@ -634,7 +731,9 @@ export function create({
     if (extend) {
       for (const ext of extend) {
         const meta = getComponentMeta(ext);
-        if (meta) Object.assign(staticDefaults, meta.staticDefaults);
+        if (meta) {
+          Object.assign(staticDefaults, meta.staticDefaults);
+        }
       }
     }
     if (variants) {
@@ -702,28 +801,94 @@ export function create({
     }
     const extCount = extMetas.length;
 
-    // Filter to only extends with computed work in their chain. `resolveDefaults`
-    // and `resolveComputed` are populated from the same transitive condition,
+    // Filter to only extends with refine work in their chain. `resolveDefaults`
+    // and `resolveRefine` are populated from the same transitive condition,
     // so one bucket is enough for both resolver paths.
-    const extMetasWithComputed: ComponentMeta[] = [];
+    const extMetasWithRefine: ComponentMeta[] = [];
     for (let i = 0; i < extCount; i++) {
       const meta = extMetas[i];
       if (meta.resolveDefaults) {
-        extMetasWithComputed.push(meta);
+        extMetasWithRefine.push(meta);
+      }
+    }
+    const extMetasWithRefineCount = extMetasWithRefine.length;
+    const shouldCollectChangedVariants = extMetasWithRefineCount > 0;
+
+    // Call-site frame captured at the `cv()` call site so refine-limit warnings
+    // can point developers at the component definition. Skipped entirely for
+    // components that can never enter the refine loop, and stripped in
+    // production via the NODE_ENV guard inside `captureCreationFrame`. The
+    // frame is captured at creation time but the underlying `.stack` string is
+    // formatted lazily on first access, so component creation stays cheap
+    // unless the warning actually fires.
+    const canTriggerRefineWarning = !!refine || extMetasWithRefineCount > 0;
+    const creationFrame = canTriggerRefineWarning
+      ? captureCreationFrame(cv)
+      : undefined;
+
+    // Function variant keys inherited from extends, filtered through this
+    // component's own variants: a static (object/shorthand) variant in this
+    // component replaces an inherited function variant for the same key.
+    // The closure is exposed on `ComponentMeta` so any further extending
+    // component can detect "ancestor's effective variant for K is a function"
+    // and skip it when overriding K with a non-function.
+    const functionVariantKeys = new Set<string>();
+    for (let i = 0; i < extCount; i++) {
+      const fnKeys = extMetas[i].functionVariantKeys;
+      for (const k of fnKeys) {
+        if (disabledVariantKeys.has(k)) continue;
+        functionVariantKeys.add(k);
+      }
+    }
+    for (let i = 0; i < functionVariantCount; i++) {
+      functionVariantKeys.add(functionVariantNames[i]);
+    }
+    for (let i = 0; i < variantEntryCount; i++) {
+      // A static variant in this component replaces an inherited function
+      // variant for the same key; from this component onward, the key is no
+      // longer a function variant.
+      functionVariantKeys.delete(variantEntryNames[i]);
+    }
+
+    // Static-variant keys in this component that override an inherited
+    // function variant. Type-level merge says child fully replaces, so the
+    // ancestor's function must not run with the child's (object-typed) value.
+    let staticVariantsOverridingExtFn: string[] | null = null;
+    if (variantEntryCount > 0 && extCount > 0) {
+      for (let i = 0; i < variantEntryCount; i++) {
+        const name = variantEntryNames[i];
+        for (let j = 0; j < extCount; j++) {
+          if (extMetas[j].functionVariantKeys.has(name)) {
+            if (!staticVariantsOverridingExtFn) {
+              staticVariantsOverridingExtFn = [];
+            }
+            staticVariantsOverridingExtFn.push(name);
+            break;
+          }
+        }
       }
     }
-    const extMetasWithComputedCount = extMetasWithComputed.length;
-    const shouldCollectChangedVariants = extMetasWithComputedCount > 0;
 
     // Pre-compute static skip key/value sets to pass to extends. These never
     // change across calls — when caller passes no skip sets, we reuse the same
     // object and avoid Set allocation.
     let staticExtSkipKeys: Set<string> | null = null;
-    if (hasDisabledVariantKeys || computedVariantCount > 0) {
+    if (
+      hasDisabledVariantKeys ||
+      functionVariantCount > 0 ||
+      staticVariantsOverridingExtFn !== null
+    ) {
       staticExtSkipKeys = new Set<string>();
-      for (const k of disabledVariantKeys) staticExtSkipKeys.add(k);
-      for (let i = 0; i < computedVariantCount; i++) {
-        staticExtSkipKeys.add(computedVariantNames[i]);
+      for (const k of disabledVariantKeys) {
+        staticExtSkipKeys.add(k);
+      }
+      for (let i = 0; i < functionVariantCount; i++) {
+        staticExtSkipKeys.add(functionVariantNames[i]);
+      }
+      if (staticVariantsOverridingExtFn) {
+        for (const k of staticVariantsOverridingExtFn) {
+          staticExtSkipKeys.add(k);
+        }
       }
     }
     // Skip values are passed directly to extends. We can reuse the same object
@@ -740,7 +905,9 @@ export function create({
     ): void {
       if (!hasAnyDisabled) {
         for (const key in input) {
-          if (Object.hasOwn(input, key)) out[key] = input[key];
+          if (Object.hasOwn(input, key)) {
+            out[key] = input[key];
+          }
         }
         return;
       }
@@ -760,12 +927,12 @@ export function create({
 
     // Pre-create resolveDefaults function — used by parents during their
     // `resolveVariantsHot`. Returns the variants set via setDefaultVariants in
-    // the computed function chain.
+    // the refine function chain.
     //
-    // When this component has no `computed` and no `extend` with work, the
+    // When this component has no `refine` and no `extend` with work, the
     // function is null — callers can skip iterating it entirely.
     const resolveDefaultsFn: ComponentMeta["resolveDefaults"] =
-      computed || extMetasWithComputedCount > 0
+      refine || extMetasWithRefineCount > 0
         ? (
             childDefaults: Record<string, unknown>,
             userProps: Record<string, unknown> = EMPTY_DEFAULTS,
@@ -787,21 +954,21 @@ export function create({
               resolvedVariants[key] = v;
             }
 
-            const computedDefaults: Record<string, unknown> = {};
+            const refineDefaults: Record<string, unknown> = {};
 
-            for (let i = 0; i < extMetasWithComputedCount; i++) {
-              const extDefaults = extMetasWithComputed[i].resolveDefaults!(
+            for (let i = 0; i < extMetasWithRefineCount; i++) {
+              const extDefaults = extMetasWithRefine[i].resolveDefaults!(
                 childDefaults,
                 userProps,
               );
               for (const k in extDefaults) {
                 if (!Object.hasOwn(extDefaults, k)) continue;
-                computedDefaults[k] = extDefaults[k];
+                refineDefaults[k] = extDefaults[k];
               }
             }
 
-            if (computed) {
-              // Filter to own variant keys so `computed.ctx.variants` matches
+            if (refine) {
+              // Filter to own variant keys so `ctx.variants` matches
               // `VariantValues<V>` when this component is used as an extend by
               // a parent that adds extra variant keys (those keys would
               // otherwise leak through `userProps`).
@@ -812,7 +979,7 @@ export function create({
                   ownVariants[k] = resolvedVariants[k];
                 }
               }
-              computed({
+              refine({
                 variants: ownVariants as VariantValues<Record<string, unknown>>,
                 setVariants: noop,
                 setDefaultVariants: (newDefaults) => {
@@ -822,7 +989,7 @@ export function create({
                     if (userProps[key] !== undefined) continue;
                     if (isVariantDisabled(config, key)) continue;
                     if (isVariantValueDisabled(config, key, value)) continue;
-                    computedDefaults[key] = value;
+                    refineDefaults[key] = value;
                   }
                 },
                 addClass: noop,
@@ -830,12 +997,12 @@ export function create({
               });
             }
 
-            return computedDefaults;
+            return refineDefaults;
           }
         : null;
 
     // Hot path: resolve variants by merging static defaults + extends'
-    // computed defaults + user-provided props.
+    // refine defaults + user-provided props.
     function resolveVariantsHot(
       propsVariants: Record<string, unknown>,
     ): Record<string, unknown> {
@@ -843,14 +1010,14 @@ export function create({
       const defaults: Record<string, unknown> = {};
       Object.assign(defaults, staticDefaults);
 
-      // Apply computed defaults from extended components (only those that have
+      // Apply refine defaults from extended components (only those that have
       // actual work to do).
-      for (let i = 0; i < extMetasWithComputedCount; i++) {
-        const meta = extMetasWithComputed[i];
-        const extComputed = meta.resolveDefaults!(defaults, propsVariants);
-        for (const k in extComputed) {
-          if (!Object.hasOwn(extComputed, k)) continue;
-          defaults[k] = extComputed[k];
+      for (let i = 0; i < extMetasWithRefineCount; i++) {
+        const meta = extMetasWithRefine[i];
+        const extDefaults = meta.resolveDefaults!(defaults, propsVariants);
+        for (const k in extDefaults) {
+          if (!Object.hasOwn(extDefaults, k)) continue;
+          defaults[k] = extDefaults[k];
         }
       }
 
@@ -864,7 +1031,9 @@ export function create({
         defaults[k] = v;
       }
 
-      if (!hasAnyDisabled) return defaults;
+      if (!hasAnyDisabled) {
+        return defaults;
+      }
 
       // Filter disabled
       const result: Record<string, unknown> = {};
@@ -872,7 +1041,7 @@ export function create({
       return result;
     }
 
-    const runComputedContext = (
+    const runRefineContext = (
       resolved: Record<string, unknown>,
       userVariantProps: Record<string, unknown>,
       filterOwnVariants: boolean,
@@ -891,28 +1060,32 @@ export function create({
       let cStyle: StyleValue | null = null;
       let changedVariants: Record<string, unknown> | null = null;
 
-      if (computed) {
+      if (refine) {
         let ownVariants = resolved;
         if (filterOwnVariants) {
           // When this component is being extended, `resolved` is the parent's
           // workingResolved (a superset of our variant keys). Filter to our own
-          // keys for `ctx.variants` so the user's `computed` callback sees the
+          // keys for `ctx.variants` so the user's `refine` callback sees the
           // shape declared by `VariantValues<V>` and not foreign parent keys.
           const filteredVariants: Record<string, unknown> = {};
           for (let i = 0; i < variantKeysLength; i++) {
             const k = variantKeys[i];
-            if (Object.hasOwn(resolved, k)) filteredVariants[k] = resolved[k];
+            if (Object.hasOwn(resolved, k)) {
+              filteredVariants[k] = resolved[k];
+            }
           }
           ownVariants = filteredVariants;
         }
-        // Lazy-init updatedVariants — many computeds only inspect `variants`
-        // or call setDefaultVariants for keys the user already set, so the
-        // copy is unnecessary in the common case.
+        // Lazy-init updatedVariants — many refine callbacks only inspect
+        // `variants` or call setDefaultVariants for keys the user already set,
+        // so the copy is unnecessary in the common case.
         let updatedVariants: Record<string, unknown> | null = null;
         const localCClasses: ClassValue[] | null = collectOutput ? [] : null;
         let localCStyle: StyleValue | null = null;
         const ensureUpdated = (): Record<string, unknown> => {
-          if (updatedVariants) return updatedVariants;
+          if (updatedVariants) {
+            return updatedVariants;
+          }
           const u: Record<string, unknown> = {};
           Object.assign(u, ownVariants);
           updatedVariants = u;
@@ -924,7 +1097,9 @@ export function create({
           protect = false,
         ) => {
           if (shouldCollectChangedVariants) {
-            if (!changedVariants) changedVariants = {};
+            if (!changedVariants) {
+              changedVariants = {};
+            }
             changedVariants[key] = value;
           }
           if (protect && protectedVariants) {
@@ -999,16 +1174,22 @@ export function create({
           },
           addStyle: (newStyle: StyleValue) => {
             if (!collectOutput) return;
-            if (!localCStyle) localCStyle = {};
+            if (!localCStyle) {
+              localCStyle = {};
+            }
             Object.assign(localCStyle, newStyle);
           },
         };
-        const result = computed(ctx);
+        const result = refine(ctx);
         if (collectOutput && result != null) {
           const r = extractClassAndStylePrebuilt(result);
-          if (r.class != null) localCClasses?.push(r.class);
+          if (r.class != null) {
+            localCClasses?.push(r.class);
+          }
           if (r.style) {
-            if (!localCStyle) localCStyle = {};
+            if (!localCStyle) {
+              localCStyle = {};
+            }
             Object.assign(localCStyle, r.style);
           }
         }
@@ -1052,14 +1233,14 @@ export function create({
       pendingProtectedVariants,
       protectedVariantKeys,
     ) => {
-      // Run `computed` (if any). May modify resolved variants and emit classes
+      // Run `refine` (if any). May modify resolved variants and emit classes
       // and styles.
       let workingResolved = resolved;
       let cClasses: ClassValue[] | null = null;
       let cStyle: StyleValue | null = null;
       let changedVariants: Record<string, unknown> | null = null;
-      if (computed) {
-        const computedResult = runComputedContext(
+      if (refine) {
+        const refineResult = runRefineContext(
           resolved,
           userVariantProps,
           true,
@@ -1068,20 +1249,20 @@ export function create({
           pendingProtectedVariants,
           protectedVariantKeys,
         );
-        workingResolved = computedResult.workingResolved;
-        cClasses = computedResult.classes;
-        cStyle = computedResult.style;
-        changedVariants = computedResult.changedVariants;
+        workingResolved = refineResult.workingResolved;
+        cClasses = refineResult.classes;
+        cStyle = refineResult.style;
+        changedVariants = refineResult.changedVariants;
       }
 
       // Run extends' contributions first (their full classes + styles) so our
       // own base style and variants apply on top, matching the original
       // ext1 → ext2 → … → current ordering.
       //
-      // Pass explicit user values plus computed changes as the extends'
-      // `userVariantProps`. This lets more-specific computed decisions stick
+      // Pass explicit user values plus refine changes as the extends'
+      // `userVariantProps`. This lets more-specific refine decisions stick
       // across re-runs while inherited static defaults can still be refined by
-      // the extended component's own computed chain.
+      // the extended component's own refine chain.
       if (hasExtend) {
         // Build skip sets to pass to extends. Reuse precomputed values when no
         // caller-provided sets need merging.
@@ -1092,7 +1273,9 @@ export function create({
           extSkipKeys = skipKeys;
         } else {
           extSkipKeys = new Set(skipKeys);
-          for (const k of staticExtSkipKeys) extSkipKeys.add(k);
+          for (const k of staticExtSkipKeys) {
+            extSkipKeys.add(k);
+          }
         }
 
         let extSkipVals: Record<string, Set<string>> | null;
@@ -1109,7 +1292,9 @@ export function create({
             const existing = extSkipVals[k];
             if (existing) {
               const merged = new Set<string>(existing);
-              for (const v of staticExtSkipValues[k]) merged.add(v);
+              for (const v of staticExtSkipValues[k]) {
+                merged.add(v);
+              }
               extSkipVals[k] = merged;
             } else {
               extSkipVals[k] = staticExtSkipValues[k];
@@ -1118,7 +1303,7 @@ export function create({
         }
 
         const extUserVariantProps =
-          extMetasWithComputedCount > 0
+          extMetasWithRefineCount > 0
             ? getExtUserVariantProps(
                 userVariantProps,
                 protectedVariants ?? null,
@@ -1165,21 +1350,24 @@ export function create({
               protectedVariantKeys,
             );
           }
-          // Only sync protected variants when a child computed resolver can
+          // Only sync protected variants when a child refine resolver can
           // observe them. Otherwise extUserVariantProps may alias caller props.
-          if (protectedVariants && extMetasWithComputedCount > 0) {
+          if (protectedVariants && extMetasWithRefineCount > 0) {
             Object.assign(extUserVariantProps, protectedVariants);
           }
         }
       }
 
       // Apply own base style (after extends' styles, matching original order).
-      if (hasBaseStyle) Object.assign(styleOut, baseStyle);
+      if (hasBaseStyle) {
+        Object.assign(styleOut, baseStyle);
+      }
 
       // Apply own variants. Skip keys/values come from caller (e.g., parent
-      // wants its own computedVariants to override this variant).
+      // wants its own function variant to override this variant).
       // `variantEntryNames` already excludes disabled keys (those with `null`
-      // value in config), so we don't re-check `disabledVariantKeys` here.
+      // value in config) and function variants, so we don't re-check
+      // `disabledVariantKeys` here.
       const ownSkipKeys = skipKeys;
       const ownSkipValues = skipValues;
       for (let i = 0; i < variantEntryCount; i++) {
@@ -1208,18 +1396,28 @@ export function create({
           if (selectedKey == null) continue;
           const v = variant.values[selectedKey];
           if (!v) continue;
-          if (v.class != null) classesOut.push(v.class as ClsxClassValue);
-          if (v.style) Object.assign(styleOut, v.style);
+          if (v.class != null) {
+            classesOut.push(v.class as ClsxClassValue);
+          }
+          if (v.style) {
+            Object.assign(styleOut, v.style);
+          }
         } else if (variant.shorthand && selectedValue === true) {
           const v = variant.shorthand;
-          if (v.class != null) classesOut.push(v.class as ClsxClassValue);
-          if (v.style) Object.assign(styleOut, v.style);
+          if (v.class != null) {
+            classesOut.push(v.class as ClsxClassValue);
+          }
+          if (v.style) {
+            Object.assign(styleOut, v.style);
+          }
         }
       }
 
-      // Apply computedVariants.
-      for (let i = 0; i < computedVariantCount; i++) {
-        const variantName = computedVariantNames[i];
+      // Apply function variants — entries in `variants` whose value is a
+      // function. They run after static variants and override any same-key
+      // inherited variant via `staticExtSkipKeys`.
+      for (let i = 0; i < functionVariantCount; i++) {
+        const variantName = functionVariantNames[i];
         if (ownSkipKeys && ownSkipKeys.has(variantName)) continue;
         const selectedValue = workingResolved[variantName];
         if (selectedValue === undefined) continue;
@@ -1231,52 +1429,35 @@ export function create({
         ) {
           continue;
         }
-        const fn = computedVariantFns[i];
+        const fn = functionVariantFns[i];
         const computedResult = fn(selectedValue);
         if (computedResult == null) continue;
         const r = extractClassAndStylePrebuilt(computedResult);
-        if (r.class != null) classesOut.push(r.class as ClsxClassValue);
-        if (r.style) Object.assign(styleOut, r.style);
+        if (r.class != null) {
+          classesOut.push(r.class as ClsxClassValue);
+        }
+        if (r.style) {
+          Object.assign(styleOut, r.style);
+        }
       }
 
-      // Apply `computed` results — must come after own variants/computedVariants.
+      // Apply `refine` results — must come after own variants (static and
+      // function).
       if (cClasses) {
         for (let i = 0; i < cClasses.length; i++) {
           classesOut.push(cClasses[i] as ClsxClassValue);
         }
       }
-      if (cStyle) Object.assign(styleOut, cStyle);
+      if (cStyle) {
+        Object.assign(styleOut, cStyle);
+      }
 
       return workingResolved;
     };
 
     const compute: ComputeFn =
-      !computed && extMetasWithComputedCount === 0
-        ? (
-            resolved,
-            userVariantProps,
-            skipKeys,
-            skipValues,
-            classesOut,
-            styleOut,
-            runState,
-            protectedVariants,
-            pendingProtectedVariants,
-            protectedVariantKeys,
-          ) => {
-            return computeOnce(
-              resolved,
-              userVariantProps,
-              skipKeys,
-              skipValues,
-              classesOut,
-              styleOut,
-              runState,
-              protectedVariants,
-              pendingProtectedVariants,
-              protectedVariantKeys,
-            );
-          }
+      !refine && extMetasWithRefineCount === 0
+        ? computeOnce
         : (
             resolved,
             userVariantProps,
@@ -1289,10 +1470,15 @@ export function create({
             pendingProtectedVariants,
             protectedVariantKeys,
           ) => {
-            runState ??= { remaining: MAX_COMPUTED_RUNS, warned: false };
+            runState ??= { remaining: MAX_REFINE_RUNS };
             protectedVariants ??= {};
             protectedVariantKeys ??= new Set<string>();
             let workingResolved = resolved;
+            // Union of variant keys that differed on non-converging iterations
+            // inside the tracking window, so the refine-limit warning can name
+            // every variant that contributed to the late-stage oscillation.
+            // Lazy-init keeps convergent loops allocation-free.
+            let unstableKeys: Set<string> | null = null;
             let lastClasses: ClsxClassValue[] = [];
             let lastStyle: StyleValue = {};
             let isFirstRun = true;
@@ -1356,10 +1542,24 @@ export function create({
                 return nextResolved;
               }
 
+              if (
+                process.env.NODE_ENV !== "production" &&
+                runState.remaining < REFINE_UNSTABLE_TRACKING_WINDOW
+              ) {
+                if (!unstableKeys) {
+                  unstableKeys = new Set<string>();
+                }
+                accumulateUnstableVariantKeys(
+                  unstableKeys,
+                  workingResolved,
+                  nextResolved,
+                );
+              }
+
               if (useDirectOutput && runState.remaining === 0) {
                 // Keep the direct output from the last allowed run. Rolling
                 // back here would drop it before the fallback copy below.
-                warnComputedLimit(runState);
+                warnRefineLimit(runState, creationFrame, unstableKeys);
                 return nextResolved;
               }
 
@@ -1379,7 +1579,7 @@ export function create({
               isFirstRun = false;
             }
 
-            warnComputedLimit(runState);
+            warnRefineLimit(runState, creationFrame, unstableKeys);
 
             for (let i = 0; i < lastClasses.length; i++) {
               classesOut.push(lastClasses[i]);
@@ -1388,7 +1588,7 @@ export function create({
             return workingResolved;
           };
 
-    const resolveComputedOnce: ResolveComputedFn = (
+    const resolveRefineOnce: ResolveRefineFn = (
       resolved,
       userVariantProps,
       filterOwnVariants = true,
@@ -1399,8 +1599,8 @@ export function create({
     ) => {
       let workingResolved = resolved;
       let changedVariants: Record<string, unknown> | null = null;
-      if (computed) {
-        const computedResult = runComputedContext(
+      if (refine) {
+        const refineResult = runRefineContext(
           resolved,
           userVariantProps,
           filterOwnVariants,
@@ -1409,21 +1609,21 @@ export function create({
           pendingProtectedVariants,
           protectedVariantKeys,
         );
-        workingResolved = computedResult.workingResolved;
-        changedVariants = computedResult.changedVariants;
+        workingResolved = refineResult.workingResolved;
+        changedVariants = refineResult.changedVariants;
       }
 
-      if (extMetasWithComputedCount > 0) {
+      if (extMetasWithRefineCount > 0) {
         const extUserVariantProps = getExtUserVariantProps(
           userVariantProps,
           protectedVariants ?? null,
           changedVariants,
         );
-        for (let i = 0; i < extMetasWithComputedCount; i++) {
-          const meta = extMetasWithComputed[i];
-          const resolveComputed = meta.resolveComputed;
-          if (!resolveComputed) continue;
-          workingResolved = resolveComputed(
+        for (let i = 0; i < extMetasWithRefineCount; i++) {
+          const meta = extMetasWithRefine[i];
+          const resolveRefine = meta.resolveRefine;
+          if (!resolveRefine) continue;
+          workingResolved = resolveRefine(
             workingResolved,
             extUserVariantProps,
             true,
@@ -1441,8 +1641,8 @@ export function create({
       return workingResolved;
     };
 
-    const resolveComputed: ResolveComputedFn | null =
-      computed || extMetasWithComputedCount > 0
+    const resolveRefine: ResolveRefineFn | null =
+      refine || extMetasWithRefineCount > 0
         ? (
             resolved,
             userVariantProps,
@@ -1452,16 +1652,21 @@ export function create({
             pendingProtectedVariants,
             protectedVariantKeys,
           ) => {
-            runState ??= { remaining: MAX_COMPUTED_RUNS, warned: false };
+            runState ??= { remaining: MAX_REFINE_RUNS };
             protectedVariants ??= {};
             protectedVariantKeys ??= new Set<string>();
             let workingResolved = resolved;
+            // Union of variant keys that differed on non-converging iterations
+            // inside the tracking window — see the compute loop above for the
+            // shared rationale. Lazy-init keeps convergent loops
+            // allocation-free.
+            let unstableKeys: Set<string> | null = null;
             let reachedLimit = true;
 
             while (runState.remaining > 0) {
               runState.remaining -= 1;
               const nextPendingProtectedVariants: Record<string, unknown> = {};
-              const nextResolved = resolveComputedOnce(
+              const nextResolved = resolveRefineOnce(
                 workingResolved,
                 userVariantProps,
                 filterOwnVariants,
@@ -1495,11 +1700,24 @@ export function create({
                 break;
               }
 
+              if (
+                process.env.NODE_ENV !== "production" &&
+                runState.remaining < REFINE_UNSTABLE_TRACKING_WINDOW
+              ) {
+                if (!unstableKeys) {
+                  unstableKeys = new Set<string>();
+                }
+                accumulateUnstableVariantKeys(
+                  unstableKeys,
+                  workingResolved,
+                  nextResolved,
+                );
+              }
               workingResolved = nextResolved;
             }
 
             if (reachedLimit) {
-              warnComputedLimit(runState);
+              warnRefineLimit(runState, creationFrame, unstableKeys);
             }
 
             return workingResolved;
@@ -1521,7 +1739,7 @@ export function create({
       Object.assign(resolved, staticDefaults);
 
       let userVariantProps: Record<string, unknown>;
-      if (extMetasWithComputedCount > 0) {
+      if (extMetasWithRefineCount > 0) {
         // Some extends need a resolveDefaults pass. They expect a variant-only
         // object as `userProps`, so we extract one.
         const variantProps: Record<string, unknown> = {};
@@ -1531,12 +1749,12 @@ export function create({
             variantProps[key] = propsRecord[key];
           }
         }
-        for (let i = 0; i < extMetasWithComputedCount; i++) {
-          const meta = extMetasWithComputed[i];
-          const extComputed = meta.resolveDefaults!(resolved, variantProps);
-          for (const k in extComputed) {
-            if (!Object.hasOwn(extComputed, k)) continue;
-            resolved[k] = extComputed[k];
+        for (let i = 0; i < extMetasWithRefineCount; i++) {
+          const meta = extMetasWithRefine[i];
+          const extDefaults = meta.resolveDefaults!(resolved, variantProps);
+          for (const k in extDefaults) {
+            if (!Object.hasOwn(extDefaults, k)) continue;
+            resolved[k] = extDefaults[k];
           }
         }
         for (const k in variantProps) {
@@ -1610,12 +1828,8 @@ export function create({
     const getVariants = (variants?: VariantValues<MergedVariants>) => {
       const variantProps = variants ?? EMPTY_DEFAULTS;
       let resolvedVariants = resolveVariantsHot(variantProps);
-      if (resolveComputed) {
-        resolvedVariants = resolveComputed(
-          resolvedVariants,
-          variantProps,
-          false,
-        );
+      if (resolveRefine) {
+        resolvedVariants = resolveRefine(resolvedVariants, variantProps, false);
       }
       return resolvedVariants as VariantValues<MergedVariants>;
     };
@@ -1642,8 +1856,9 @@ export function create({
       staticDefaults,
       resolveDefaults: resolveDefaultsFn,
       compute,
-      resolveComputed,
+      resolveRefine,
       transformClass,
+      functionVariantKeys,
     };
 
     const initComponent = <
@@ -1667,7 +1882,7 @@ export function create({
     const defaultComponent = ((props: ComponentProps<MergedVariants> = {}) => {
       const { className, style } = computeResult(props);
       return { class: className, style };
-    }) as CVComponent<V, CV, E>;
+    }) as CVComponent<V, E>;
     initComponent(defaultComponent, inputPropsKeys, (props = {}) => {
       return computeResult(props).style;
     });