in reply to API design - if you're expecting a scalar and an array ....

Sorry I'm confused, why do you pass named parameters as a arr-ref instead of a hash-ref?

  $nest->nest(newlevel => [attr1 => 1, attr2 => 2]);

instead of

 $nest->nest(newlevel => {attr1 => 1, attr2 => 2});

To your topic, I think it's good practice to use a literal hash-ref for named parameters when your mixing with positional parameters (or expect to do so later), like in this example.

Cheers Rolf