1. Basic navigator concepts
The core concept of the navigator revolves around navigation states. These are essentially slash delimited paths, wrapped in convenience class instances called NavigationState. This class you'll use fairly frequently, for it not only takes care of putting the slashes in consistently, it also contains convenience methods to compare and modify states. You change the state of your application by requesting a new state, like: navigator.request("gallery"). The path will automatically be complemented to include the right beginning and trailing slashes, so if granted, your application will navigate to the state called /gallery/.
The idea of these navigation states is that they're built like a cascade. You add elements of your application to a certain state, and the navigator will make sure it responds to changes in that state or states further down stream. For example, you can add your gallery component to a state called /gallery/. If your application state then changes to /gallery/fishes/ your component will be notified of the change. The same holds true for a state like /gallery/fishes/1979/. If however the application navigates to /contact/ or /contact/headquarters/, it will not be notified of the change, and most likely be ordered to hide itself.
The kind of notification an element gets from the navigator is based on the behavior it was added with. All notifications happen through direct method calls, which is why your element needs to implement the correct interfaces. These behavior interfaces contain methods for transitioning in and out, getting update calls, swapping content in ranged lists and, very important, validate states.
To ensure that your application can never navigate to an 'invalid' state, part of the library deals with validating requests, though most of this happens automatically. For example, because the navigator knows if you have a component registered to /about/, the navigator.request("about") will be granted immediately. However, if you want to make sure that your gallery component does not navigate past the amount of pictures in your database, you can deny requests that exceed the boundaries of you application. The item at /gallery/5/ may be completely fine, but /gallery/42/ may not be. For the case that your application needs a little time to decide whether a state is valid or not, there's also support for asynchronous validation. This whole validation business makes the use of a deeplinking feature a breeze.