One other change to call out:

The existing logic today prevents setInitialRoute from working if the app specifies an initialRoute. This will give setInitialRoute precedence over the app's initialRoute parameter in the case where the setInitialRoute is not set to /.

I'm not particular familiar with the internals of the App Widgets, but generally LGTM.

I'm not sure this is really the direction I would have liked us to go with this... it doesn't seem really in sync with either my Router work or Hans' route transition theme work. For this kind of low-level change in the future please make sure to get reviews from @HansMuller, @goderbauer, and/or myself.

(i don't think we need to revert this, it's fine to leave as is.)

Around the time of this PR, flutter_gallery_ios32__transition_perf got much more flaky.

@Hixie so we know what to watch for for the future, what did you have in mind? I get the impression from your branch that *App will compose a Router which composes a Navigator.

This PR just makes the 3 *App's APIs consistent. Or did you intent for the Router to only be configured by the MaterialApp but not WidgetsApp?

Hans' transition theme is further down the widget tree and should be orthogonal.

Right, but Navigator doesn't know about routes, and the idea is to move away from routes and more towards pages.

@Hixie do you have an up to date doc that explains the high level logistics of the routing solution you're working on?

Ah I see, so master...Hixie:router#diff-c798125dc01f08ce6bd3a0931482078bR627 is just a parallel backward compatibility mechanism apart from pages?

The lines above said "it's most common to use the navigator created by the [Router] which itself is created and configured by a [WidgetsApp] or a [MaterialApp] widget". I thought the *App implicitly translated the routes map into pages before creating a Router internally.

Will watch out for navigation related PRs in the future.

@matthew-carroll no, only the API docs on my branch.

@dnfield I have a question regarding one of the asserts added to WidgetsApp in this commit. I'm trying to create a simple one page app that doesn't have any need of routes, but I want to use the WidgetsApp class so that I can get the safe area.

Before this commit I had a simple implementation like this:

  @override
  Widget build(BuildContext context) {
    return new WidgetsApp(
      builder: (BuildContext context, Widget child) {
        return MyStuff();
      },
      textStyle: const TextStyle(color: Colors.black),
      color: Color(0xFF0000FF),
    );
  }
}

Which was broken by this assertion:
assert(onGenerateRoute != null || pageRouteBuilder != null) in packages/flutter/lib/src/widgets/app.dart

Since I'm not using routes, I don't think should need to have either of those.
I was able to fix it like this:

class MyWidgetsApp extends StatelessWidget {
  @override
  Widget build(BuildContext context) {
    return new WidgetsApp(
      builder: (BuildContext context, Widget child) {
        return MyStuff();
      },
      pageRouteBuilder: pageRouteBuilder,
      textStyle: const TextStyle(color: Colors.black),
      color: Color(0xFF0000FF),
    );
  }

  PageRoute pageRouteBuilder(RouteSettings settings, WidgetBuilder builder) {
    return MaterialPageRoute(settings: settings, builder: builder);
  }
}

So I'm wondering if I'm doing this correctly and also if this was an intentional change. The flutter docs around this are not very clear.

Hmm. This was intended to be a non-breaking change.

The assert message on the one that is being violated was meant to explain what to do here - if you're not providing a way to do routing, you need apageRouteBuilder is needed to avoid making an incorrect assumption about what kind of routing transitions you would want if any do occur.

I suppose we could add a check to that assert for something like onGenerateRoute != null || (routes.length > 1 && pageRouteBuilder != null), which I think would unbreak you here and still work. Of course we'd be in a mess if someone added routes during runtime, but there are a few other places where the logic breaks down in that case anyway.

What do you think of that?

Actually, this should be the correct assert:

 assert(
         builder != null ||
         onGenerateRoute != null ||
         pageRouteBuilder != null,
         'If neither builder nor onGenerateRoute are provided, the '
         'pageRouteBuilder must be specified so that the default handler '
         'will know what kind of PageRoute transition to build.'
       ),

Let's continue discussion at the linked PR #23976

@roydaw The MaterialApp and WidgetsApp builder parameter was really intended to enable adding widgets to the app's BuildContext, "above" the app's home. A simple app like the one you've described would typically be written like this:

  @override
  Widget build(BuildContext context) {
    return new WidgetsApp(
      home: MyStuff();
      textStyle: const TextStyle(color: Colors.black),
      color: Color(0xFF0000FF),
    );
  }

That said, we didn't intend to introduce a backwards-incompatible change here. In other words, just specifying a builder should still work.