lit-navigation-router 0.5.0 → 0.6.0

package/src/routes.ts

@@ -27,40 +27,24 @@ export interface PathRouteConfig extends BaseRouteConfig {
 }
 
 /**
- * A RouteConfig that matches against a given [`URLPattern`](https://developer.mozilla.org/en-US/docs/Web/API/URLPattern)
+ * A RouteConfig that matches against a given [`URLPattern`](https://developer.mozilla.org/en-US/docs/Web/API/URLPattern).
  *
- * While `URLPattern` can match against protocols, hostnames, and ports,
- * routes will only be checked for matches if they're part of the current
- * origin. This means the pattern is limited to checking `pathname`, `search`
- * and `hash`.
+ * Routes are only checked within the current origin, so only `pathname`,
+ * `search` and `hash` are matched.
  */
 export interface URLPatternRouteConfig extends BaseRouteConfig {
   pattern: URLPatternLike;
 }
 
 /**
- * The part of `URLPattern` this router uses.
- *
- * Declared structurally rather than referencing the global so the emitted
- * `.d.ts` is self-contained: the `/// <reference types="urlpattern-polyfill" />`
- * above is not carried into declaration output, and `URLPattern` is not in
- * TypeScript's bundled `lib.dom`, so a published package typed against the
- * global fails a consumer build with `TS2304: Cannot find name 'URLPattern'`.
- * A real `URLPattern` satisfies this, so passing one still type-checks.
+ * The part of `URLPattern` this router uses. Structural, not a reference to the
+ * global: `URLPattern` is not in TypeScript's `lib.dom`, so typing against it
+ * fails a consumer build with `TS2304`.
  */
 export interface URLPatternLike {
-  /**
-   * The pathname pattern string, as `URLPattern.prototype.pathname` returns
-   * it. Read to tell a trailing wildcard from any other positional group —
-   * the groups object alone cannot (see `tailOf`).
-   */
+  /** Read by `tailOf`, which the groups object alone cannot answer. */
   readonly pathname: string;
-  /**
-   * The hash pattern string. `'*'` means the route places no constraint on the
-   * fragment, which is what `URLPattern` fills in for any component the caller
-   * omits. `Router` reads this to decide whether a fragment-only navigation is
-   * its business or the browser's.
-   */
+  /** `'*'` means unconstrained. `Router` gates hash interception on this. */
   readonly hash: string;
   test(input: RouteLocation): boolean;
   exec(input: RouteLocation): {
@@ -71,13 +55,9 @@ export interface URLPatternLike {
 }
 
 /**
- * The parts of a location this router matches against, split out of a path
- * string by `parseLocation`.
- *
- * `search` and `hash` carry no leading `?` or `#`. `URLPattern` canonicalises
- * either form away on an init input, but only for a real `URLPattern` — the
- * structural `URLPatternLike` above admits other implementations, so the
- * delimiters are stripped here rather than left to the pattern.
+ * The parts of a location this router matches against. `search` and `hash`
+ * carry no leading `?` or `#`: a real `URLPattern` canonicalises either form
+ * away, but `URLPatternLike` admits implementations that do not.
  */
 export interface RouteLocation {
   pathname: string;
@@ -86,11 +66,8 @@ export interface RouteLocation {
 }
 
 /**
- * Splits `path` into the components a pattern is matched against.
- *
- * Deliberately not `new URL(path, origin)`: a nested controller's path is a
- * *tail* — a bare relative segment like `abc` — which `URL` would resolve
- * against the current directory and mangle.
+ * Not `new URL(path, origin)`: a nested controller's path is a tail, a bare
+ * relative segment like `abc`, which `URL` would resolve and mangle.
  */
 const parseLocation = (path: string): RouteLocation => {
   const hashIndex = path.indexOf('#');
@@ -111,16 +88,10 @@ const formatLocation = (
 ): string =>
   pathname + (search === '' ? '' : `?${search}`) + (hash === '' ? '' : `#${hash}`);
 
-/**
- * A description of a route, which path or pattern to match against, and a
- * render() callback used to render a match to the outlet.
- */
 export type RouteConfig = PathRouteConfig | URLPatternRouteConfig;
 
-// A cache of URLPatterns created for PathRouteConfig.
-// Rather than converting all given RoutConfigs to URLPatternRouteConfig, this
-// lets us make `routes` mutable so users can add new PathRouteConfigs
-// dynamically.
+// Keyed by config object so `routes` can stay a plain mutable array that users
+// push new PathRouteConfigs onto.
 const patternCache = new WeakMap<PathRouteConfig, URLPatternLike>();
 
 const isPatternConfig = (route: RouteConfig): route is URLPatternRouteConfig =>
@@ -138,27 +109,17 @@ const getPattern = (route: RouteConfig): URLPatternLike => {
 };
 
 /**
- * Matches a pathname pattern that ends in a wildcard, in the forms
- * `URLPattern.prototype.pathname` regenerates one: a bare `*` — which a
- * trailing `(.*)` also normalises to — or `{*}`, which the generator emits for
- * a wildcard after a modified group, e.g. `/docs{/}?*`. Either may be
- * optional (`*?`). Not a wildcard: an escaped `\*`, or a `*` that is the
- * modifier on a group (`(\d+)*`, `{/}*`) or on a named param (`:rest*`).
- * Those exclusions matter when an earlier positional group exists —
- * `/x/(\d+)/:rest*` — since that group would otherwise be taken for the tail.
+ * A trailing wildcard as `URLPattern.prototype.pathname` regenerates it: `*` or
+ * `{*}`, optionally `?`. Excludes an escaped `\*` and a `*` modifying a group
+ * or named param (`(\d+)*`, `{/}*`, `:rest*`), which would otherwise let an
+ * earlier group be taken for the tail. See #4.
  */
 const TRAILING_WILDCARD = /(?:(?<![\\)}]|:[\w$]+)\*|\{\*\})\??$/;
 
 /**
- * The tail of a match — what a trailing wildcard (`/foo/*`) captured — or
- * undefined when the pattern has none.
- *
- * Decided from the pattern, not from the groups object: an unnamed regex group
- * (`/post/(\d+)`) and a wildcard that is not last (`/foo/*` followed by
- * `/bar`) are keyed by index exactly as a tail is, and reading either as one
- * truncated `link()` and handed a child the wrong segment. When a trailing
- * wildcard is present it is the last group in the pattern, so its key is the
- * highest positional index.
+ * What a trailing wildcard captured, or undefined when there is none. Decided
+ * from the pattern, not the groups object: an unnamed group (`/post/(\d+)`) and
+ * a non-final wildcard are keyed by index exactly as a tail is. See #4.
  */
 const tailOf = (
   route: RouteConfig,
@@ -169,8 +130,7 @@ const tailOf = (
   }
   let tailIndex = -1;
   for (const key of Object.keys(params)) {
-    // Numeric, not lexicographic: '9' sorts above '10' as a string, so a
-    // pattern with eleven or more wildcards picked group 9 as its tail.
+    // Numeric, not lexicographic: '9' > '10' as strings.
     if (/^\d+$/.test(key) && Number(key) > tailIndex) {
       tailIndex = Number(key);
     }
@@ -178,6 +138,201 @@ const tailOf = (
   return tailIndex < 0 ? undefined : params[String(tailIndex)];
 };
 
+/**
+ * One piece of a pathname pattern, as `parsePattern` understands it.
+ */
+type PatternNode =
+  | {kind: 'literal'; text: string}
+  | {kind: 'param'; name: string; optional: boolean}
+  | {kind: 'wildcard'; index: number; optional: boolean}
+  | {kind: 'group'; nodes: Array<PatternNode>; optional: boolean};
+
+/**
+ * Parses the subset of `URLPattern` pathname syntax that can be run backwards:
+ * literals, `:name`, `*`, and `{...}` groups, each optionally `?`.
+ *
+ * A regex group cannot be reversed, and `+` or `*` repetition has no single
+ * answer, so both throw rather than guess. Named the route, not the pattern,
+ * because the caller passed a name and that is what they can act on.
+ */
+const parsePattern = (pattern: string, name: string): Array<PatternNode> => {
+  let i = 0;
+  let positional = 0;
+
+  const takeModifier = (): boolean => {
+    const mod = pattern[i];
+    if (mod === '?') {
+      i++;
+      return true;
+    }
+    if (mod === '+' || mod === '*') {
+      throw new Error(
+        `Cannot build a link to '${name}': the repeating modifier '${mod}' in ` +
+          `'${pattern}' has no single reverse.`
+      );
+    }
+    return false;
+  };
+
+  const parseNodes = (untilBrace: boolean): Array<PatternNode> => {
+    const nodes: Array<PatternNode> = [];
+    let literal = '';
+    const flush = () => {
+      if (literal !== '') {
+        nodes.push({kind: 'literal', text: literal});
+        literal = '';
+      }
+    };
+
+    while (i < pattern.length) {
+      const c = pattern[i];
+      if (untilBrace && c === '}') {
+        break;
+      }
+      if (c === '\\') {
+        literal += pattern[i + 1] ?? '';
+        i += 2;
+        continue;
+      }
+      if (c === '(') {
+        throw new Error(
+          `Cannot build a link to '${name}': '${pattern}' contains a regular ` +
+            `expression group, which cannot be reversed. Use a named parameter.`
+        );
+      }
+      if (c === '{') {
+        flush();
+        i++;
+        const inner = parseNodes(true);
+        if (pattern[i] !== '}') {
+          throw new Error(
+            `Cannot build a link to '${name}': unbalanced '{' in '${pattern}'.`
+          );
+        }
+        i++;
+        nodes.push({kind: 'group', nodes: inner, optional: takeModifier()});
+        continue;
+      }
+      const named = c === ':' ? /^:([A-Za-z0-9_$]+)/.exec(pattern.slice(i)) : null;
+      if (named !== null) {
+        flush();
+        i += named[0].length;
+        nodes.push({kind: 'param', name: named[1], optional: takeModifier()});
+        continue;
+      }
+      if (c === '*') {
+        flush();
+        i++;
+        nodes.push({
+          kind: 'wildcard',
+          index: positional++,
+          optional: takeModifier(),
+        });
+        continue;
+      }
+      literal += c;
+      i++;
+    }
+    flush();
+    return nodes;
+  };
+
+  return parseNodes(false);
+};
+
+/** The highest wildcard index in `nodes`, or -1 when there is none. */
+const maxWildcard = (nodes: Array<PatternNode>): number =>
+  nodes.reduce(
+    (max, node) =>
+      node.kind === 'wildcard'
+        ? Math.max(max, node.index)
+        : node.kind === 'group'
+          ? Math.max(max, maxWildcard(node.nodes))
+          : max,
+    -1
+  );
+
+/**
+ * Builds a pathname from `nodes`, collecting the names of any parameters the
+ * caller did not supply.
+ *
+ * `tailIndex` is the wildcard that a trailing `/*` produced, or -1. That one
+ * may be left out: an empty tail is the index of a nested route space, which
+ * is what `linkTo('docs')` should mean. Any other wildcard is required, since
+ * dropping it would silently join the segments around it.
+ */
+const fillNodes = (
+  nodes: Array<PatternNode>,
+  params: {[key: string]: string | undefined},
+  tailIndex: number,
+  missing: Array<string>
+): string => {
+  let out = '';
+  for (const node of nodes) {
+    switch (node.kind) {
+      case 'literal':
+        out += node.text;
+        break;
+      case 'param': {
+        const value = params[node.name];
+        if (value === undefined) {
+          if (!node.optional) {
+            missing.push(node.name);
+          }
+        } else {
+          out += value;
+        }
+        break;
+      }
+      case 'wildcard': {
+        const value = params[String(node.index)];
+        if (value === undefined) {
+          if (!node.optional && node.index !== tailIndex) {
+            missing.push(String(node.index));
+          }
+        } else {
+          out += value;
+        }
+        break;
+      }
+      case 'group': {
+        const before = missing.length;
+        const text = fillNodes(node.nodes, params, tailIndex, missing);
+        if (missing.length > before && node.optional) {
+          // The whole point of an optional group: drop it, and the parameters
+          // it wanted stop being missing.
+          missing.length = before;
+        } else {
+          out += text;
+        }
+        break;
+      }
+    }
+  }
+  return out;
+};
+
+/** Runs a pathname pattern backwards. Throws naming every missing parameter. */
+const fillPattern = (
+  pattern: string,
+  params: {[key: string]: string | undefined},
+  name: string
+): string => {
+  const nodes = parsePattern(pattern, name);
+  const missing: Array<string> = [];
+  const tailIndex = TRAILING_WILDCARD.test(pattern) ? maxWildcard(nodes) : -1;
+  const text = fillNodes(nodes, params, tailIndex, missing);
+  if (missing.length > 0) {
+    throw new Error(
+      `Cannot build a link to '${name}': missing parameter` +
+        `${missing.length > 1 ? 's' : ''} ` +
+        missing.map((m) => `'${m}'`).join(', ') +
+        ` for pattern '${pattern}'.`
+    );
+  }
+  return text;
+};
+
 /**
  * A reactive controller that performs location-based routing using a
  * configuration of URL patterns and associated render callbacks.
@@ -185,60 +340,28 @@ const tailOf = (
 export class Routes implements ReactiveController {
   private readonly _host: ReactiveControllerHost & HTMLElement;
 
-  /*
-   * The currently installed set of routes in precedence order.
-   *
-   * This array is mutable. To dynamically add a new route you can write:
-   *
-   * ```ts
-   * this._routes.routes.push({
-   *   path: '/foo',
-   *   render: () => html`<p>Foo</p>`,
-   * });
-   * ```
-   *
-   * Mutating this property does not trigger any route transitions. If the
-   * changes may result is a different route matching for the current path, you
-   * must instigate a route update with `goto()`.
+  /**
+   * The installed routes, in precedence order. Mutable, but mutating it starts
+   * no route transition; call `goto()` if a different route now matches.
    */
   routes: Array<RouteConfig> = [];
 
   /**
-   * A default fallback route which will always be matched if none of the
-   * {@link routes} match. Behaves like a `/*` route: `params[0]` is the whole
-   * pathname minus its leading slash, and is handed to child controllers as
-   * their tail. A nested controller's own pathname is a tail, with no leading
-   * slash; the fallback accepts that too.
+   * Matched when no route in {@link routes} does. Behaves like `/*`, so
+   * `params[0]` is the whole pathname minus any leading slash.
    */
   fallback?: BaseRouteConfig;
 
-  /*
-   * The current set of child Routes controllers. These are connected via
-   * the routes-connected event.
-   */
   private readonly _childRoutes: Array<Routes> = [];
 
   private _parentRoutes: Routes | undefined;
 
-  /*
-   * State related to the current matching route.
-   *
-   * We keep this so that consuming code can access current parameters, and so
-   * that we can propagate tail matches to child routes if they are added after
-   * navigation / matching.
-   */
   /** Monotonic goto counter; see the last-goto-wins note in goto(). */
   private _gotoSeq = 0;
 
   private _currentPathname: string | undefined;
   private _currentTail: string | undefined;
-  /**
-   * The search and hash of the current location.
-   *
-   * Ambient rather than tailed: only the pathname nests, so a child controller
-   * is handed the parent's tail as its pathname but the *same* search and
-   * hash. There is no meaningful way to split a fragment across a route tree.
-   */
+  /** Ambient, not tailed: only the pathname nests. */
   private _currentSearch = '';
   private _currentHash = '';
   private _currentRoute: RouteConfig | undefined;
@@ -246,12 +369,8 @@ export class Routes implements ReactiveController {
     [key: string]: string | undefined;
   } = {};
 
-  /**
-   * Callback to call when this controller is disconnected.
-   *
-   * It's critical to call this immediately in hostDisconnected so that this
-   * controller instance doesn't receive a tail match meant for another route.
-   */
+  /** Must run in hostDisconnected, or this controller can receive another
+   * route's tail match. */
   // TODO (justinfagnani): Do we need this now that we have a direct reference
   // to the parent? We can call `this._parentRoutes.disconnect(this)`.
   private _onDisconnect: (() => void) | undefined;
@@ -282,17 +401,73 @@ export class Routes implements ReactiveController {
   }
 
   /**
-   * Navigates this routes controller to `pathname`.
+   * A URL for the route named `name`, with `params` substituted into its
+   * pattern.
    *
-   * This does not navigate parent routes, so it isn't (yet) a general page
-   * navigation API. It does navigate child routes if pathname matches a
-   * pattern with a tail wildcard pattern (`/*`).
+   * Lets a component say which route it means instead of where that route
+   * currently lives, so moving a route subtree does not silently break every
+   * hardcoded link inside it.
+   *
+   * Resolution covers the mounted controller tree: this controller, its
+   * ancestors, and any descendant that has rendered. A route in a branch that
+   * has not mounted yet is not addressable, because the mapping from a parent
+   * route to its child controller only exists once that parent has rendered.
+   * An unknown or ambiguous name throws rather than producing a wrong URL.
+   */
+  linkTo(
+    name: string,
+    params: {[key: string]: string | undefined} = {}
+  ): string {
+    let root: Routes = this;
+    while (root._parentRoutes !== undefined) {
+      root = root._parentRoutes;
+    }
+
+    const found: Array<{owner: Routes; route: RouteConfig}> = [];
+    const visit = (routes: Routes, seen: Set<Routes>) => {
+      // Cycle guard, matching `_supersede`; see the note there.
+      if (seen.has(routes)) {
+        return;
+      }
+      seen.add(routes);
+      for (const route of routes.routes) {
+        if (route.name === name) {
+          found.push({owner: routes, route});
+        }
+      }
+      for (const child of routes._childRoutes) {
+        visit(child, seen);
+      }
+    };
+    visit(root, new Set());
+
+    if (found.length === 0) {
+      throw new Error(
+        `No route named '${name}' in the mounted route tree. Names are only ` +
+          `resolvable once the controller holding them has rendered.`
+      );
+    }
+    if (found.length > 1) {
+      throw new Error(
+        `More than one route named '${name}' in the mounted route tree.`
+      );
+    }
+
+    const {owner, route} = found[0];
+    // The owner's own segment is being replaced by the generated one, so the
+    // prefix is everything above it.
+    const prefix = owner._parentRoutes?.link() ?? '';
+    return prefix + fillPattern(getPattern(route).pathname, params, name);
+  }
+
+  /**
+   * Navigates this controller to `path`, which may carry a search and hash.
+   * Navigates child routes but not parent ones, so it is not yet a general page
+   * navigation API.
    *
-   * Pass `options.signal` to make the navigation abandonable. `enter()` is
-   * awaited, so a second `goto()` can start — and finish — while the first is
-   * still resolving its route; without a signal the slower one commits last
-   * and the outlet ends up on a route the URL has already left. `Router`
-   * threads `NavigateEvent.signal` through for exactly this reason.
+   * `options.signal` makes the navigation abandonable. `enter()` is awaited, so
+   * a second `goto()` can finish while the first is still resolving; without a
+   * signal the slower one commits last onto a route the URL has left.
    */
   async goto(path: string, options?: {signal?: AbortSignal}) {
     // TODO (justinfagnani): handle absolute vs relative paths separately.
@@ -300,23 +475,17 @@ export class Routes implements ReactiveController {
     const location = parseLocation(path);
     const {pathname} = location;
 
-    // Last-goto-wins, per controller. The navigation signal alone is not
-    // enough: a child controller mounts as a *result* of its parent's render,
-    // so its first goto() comes from `_onRoutesConnected` — after the parent's
-    // navigation has already finished, and therefore with a signal that will
-    // never abort. Without this counter a slow first child load commits over a
-    // newer one. This also keeps `Routes` correct when used on its own, with
-    // no `Router` and no Navigation API in the picture.
+    // Last-goto-wins. The signal alone is not enough: a child's first goto()
+    // comes from `_onRoutesConnected`, after the parent's navigation finished,
+    // so its signal never aborts. Also keeps `Routes` correct standalone.
     const seq = ++this._gotoSeq;
     let tail: string | undefined;
 
     if (this.routes.length === 0 && this.fallback === undefined) {
-      // If a routes controller has none of its own routes it acts like it has
-      // one route of `/*` so that it passes the whole pathname as a tail
-      // match.
+      // No routes of its own acts as a single `/*`, passing the whole pathname
+      // on as a tail.
       tail = pathname;
       this._currentPathname = '';
-      // Simulate a tail group with the whole pathname
       this._currentParams = {0: tail};
     } else {
       const match = this._match(location);
@@ -327,17 +496,14 @@ export class Routes implements ReactiveController {
       tail = match.tail;
       if (typeof route.enter === 'function') {
         const success = await route.enter(params);
-        // If enter() returns false, cancel this navigation
         if (success === false) {
           return;
         }
       }
-      // A newer navigation superseded this one while `enter` was awaiting.
-      // Committing now would swap the outlet onto a route the URL has left.
+      // Superseded while `enter` awaited; committing would strand the outlet.
       if (options?.signal?.aborted === true || seq !== this._gotoSeq) {
         return;
       }
-      // Only update route state if the enter handler completes successfully
       this._currentRoute = route;
       this._currentParams = params;
       this._currentPathname =
@@ -349,24 +515,12 @@ export class Routes implements ReactiveController {
     this._currentSearch = location.search;
     this._currentHash = location.hash;
 
-    // Propagate the tail match to children — deliberately NOT awaited.
-    //
-    // Awaiting looks like it would make `navigation.finished` cover the whole
-    // tree, and an earlier revision of this fork did it. It is wrong twice
-    // over. At this point `requestUpdate()` has not run, so `_childRoutes`
-    // still holds the *outgoing* branch's controller: awaiting it gates the
-    // parent's outlet swap on an `enter()` for a tail that controller will
-    // never render (a hung one blocks the navigation forever), and if that
-    // child has no route for the new tail its `No route found` throw
-    // propagates out of here and `requestUpdate()` below never runs — URL
-    // committed, outlet stranded, i.e. this fork's own thesis bug one level
-    // down. Nested supersession is handled by the goto counter above, not by
-    // awaiting. `_routeChild` covers the per-child filtering and error policy.
+    // Not awaited. `requestUpdate()` has not run, so `_childRoutes` still holds
+    // the outgoing branch: awaiting gates the parent's swap on a controller
+    // that will never render, and its `No route found` would skip
+    // `requestUpdate()` below and strand the outlet on a committed URL.
     //
-    // Runs whether or not there is a tail. A route without one has nothing for
-    // the children to render, but they must still be superseded — otherwise a
-    // child mid-`enter()` for the previous tail stays current and commits over
-    // a URL that has moved on.
+    // Runs even with no tail, so children still get superseded. See #7.
     for (const childRoutes of this._childRoutes) {
       this._routeChild(childRoutes, tail);
     }
@@ -388,26 +542,12 @@ export class Routes implements ReactiveController {
   }
 
   /**
-   * Hands a tail match to a child controller. Shared by the propagation loop in
-   * `goto()` and the late-mount path in `_onRoutesConnected`, so that identical
-   * input cannot be silent on one and an uncaught global throw on the other.
+   * Hands a tail match to a child. Shared by `goto()`'s propagation loop and the
+   * late-mount path, so identical input behaves identically on both.
    *
-   * A child with no route for the new tail is the expected case, not an error —
-   * the outgoing branch mid-swap, or a deep link to a path the child cannot
-   * render. Filtered structurally rather than by swallowing every rejection, so
-   * a genuine `enter()` rejection still surfaces the way it does upstream.
-   * Skipping must still supersede: `goto()` is where the counter is bumped, so
-   * returning without it would leave an in-flight child navigation current,
-   * free to commit over a URL that has moved on. A parent route with no tail
-   * at all is the same case: nothing to route, but still something to stand
-   * down.
-   *
-   * No abort signal is threaded through, and the goto is deliberately not
-   * awaited. The parent commits its own state before children run, so a child
-   * handed an already-aborted signal stands down with no newer goto() arriving
-   * to correct it, leaving the nested outlet stuck — reachable, because a
-   * hash-only navigation aborts the outstanding one without producing a
-   * replacement. Supersession is the counter's job.
+   * A child with no route for the tail is expected, not an error: the outgoing
+   * branch mid-swap, or a deep link it cannot render. Filtered structurally so
+   * a genuine `enter()` rejection still surfaces. Skipping must still supersede.
    */
   private _routeChild(child: Routes, tail: string | undefined) {
     if (tail === undefined) {
@@ -429,43 +569,26 @@ export class Routes implements ReactiveController {
     });
   }
 
-  /**
-   * Invalidate any in-flight `goto()` on this controller without starting a
-   * new one. Same-class access, so `_gotoSeq` stays private to `Routes`.
-   */
+  /** Invalidate any in-flight `goto()` here without starting a new one. */
   private _supersede(seen: Set<Routes> = new Set()): void {
-    // Unreachable defence in depth. Upstream *can* produce a `_childRoutes`
-    // cycle — a host carrying two Routes controllers, disconnected and
-    // reconnected, ends up with each registered as the other's child — but
-    // `hostDisconnected` below removes the listener that causes it, and a test
-    // asserts the cycle cannot form. Kept because an unguarded recursive walk
-    // over a cycle is a stack overflow rather than a misrender.
+    // Defence in depth: a `_childRoutes` cycle cannot form (hostDisconnected,
+    // plus a test), but an unguarded walk over one is a stack overflow.
     if (seen.has(this)) {
       return;
     }
     seen.add(this);
     this._gotoSeq++;
-    // Recursive: on the navigating branch the child's own propagation loop
-    // reaches the grandchildren, but a skipped child never runs one — so
-    // without this an in-flight grandchild `enter()` stays current and commits
-    // over a URL that has moved on, the same defect one level deeper.
+    // A skipped child never runs its own propagation loop, so recurse or an
+    // in-flight grandchild `enter()` stays current.
     for (const child of this._childRoutes) {
       child._supersede(seen);
     }
   }
 
   /**
-   * True when this controller, or any controller below it, has a route that
-   * constrains the hash.
-   *
-   * `Router` gates interception of fragment-only navigation on this. Left
-   * ungated, a pathname-only app would have every in-page anchor swallowed and
-   * re-rendered instead of scrolled; gated, such an app behaves exactly as it
-   * did before hash routes existed.
-   *
-   * Walks children because a nested controller may route on the hash while the
-   * top-level `Router` does not — and only the top-level one sees the
-   * navigate event.
+   * True when this controller or any below it constrains the hash. `Router`
+   * gates fragment-only interception on this, so a pathname-only app keeps
+   * native scrolling. Walks children because only the root sees the event.
    */
   protected _constrainsHash(seen: Set<Routes> = new Set()): boolean {
     // Cycle guard, matching `_supersede`; see the note there.
@@ -480,35 +603,25 @@ export class Routes implements ReactiveController {
   }
 
   /**
-   * True when this controller can render `path` — i.e. a route matches, or
-   * a fallback is configured.
-   *
-   * `Router` gates interception on this: intercepting a path we cannot render
-   * commits the URL and then throws out of `goto()`, leaving the address bar
-   * moved and the outlet stale. Letting the browser handle it instead means a
-   * server-rendered page, an export endpoint, or a GET form still works.
+   * True when this controller can render `path`. `Router` gates interception on
+   * this: intercepting what we cannot render commits the URL and then throws,
+   * leaving the address bar moved and the outlet stale.
    */
   hasRouteFor(path: string): boolean {
-    // A fallback matches everything, and a controller with no routes of its own
-    // behaves as if it had a single `/*` route (goto()'s special case). Either
-    // way the answer is yes without running a single pattern — worth
-    // short-circuiting, since `Router` asks this on every navigation.
+    // A fallback matches everything, and no routes behaves as one `/*`. Worth
+    // short-circuiting: `Router` asks this on every navigation.
     if (this.fallback !== undefined || this.routes.length === 0) {
       return true;
     }
-    // `test()`, not `_match()`: this only needs the yes/no, and `exec()` pays
-    // ~8x on a hit to build a groups object the caller would throw away.
+    // `test()`, not `_match()`: `exec()` pays ~8x on a hit to build groups the
+    // caller would throw away.
     const location = parseLocation(path);
     return this.routes.some((r) => getPattern(r).test(location));
   }
 
   /**
-   * Matches `pathname` against the installed routes and returns the first match
-   * with its parsed parameters, or the fallback's match if one is configured.
-   *
-   * One `exec()` per candidate rather than `test()` to select and `exec()` to
-   * extract: that ran the winning pattern twice, and every caller that wants a
-   * route wants its params too.
+   * The first route matching `location`, or the fallback's match. One `exec()`
+   * per candidate; selecting with `test()` first ran the winner twice.
    */
   private _match(location: RouteLocation):
     | {
@@ -523,10 +636,8 @@ export class Routes implements ReactiveController {
         const params: {[key: string]: string | undefined} = {
           ...result.pathname.groups,
         };
-        // Named groups only. A positional group is keyed by index in every
-        // component independently, so `/child/*` with a hash of `*` yields a
-        // "0" in both — and `tailOf` picks the tail by highest numeric key.
-        // Merging them would let a fragment masquerade as the tail.
+        // Named only. Every component numbers positional groups from zero, so
+        // a merged "0" could masquerade as the tail. See #13.
         for (const groups of [result.search.groups, result.hash.groups]) {
           for (const [key, value] of Object.entries(groups)) {
             if (!/^\d+$/.test(key)) {
@@ -540,12 +651,8 @@ export class Routes implements ReactiveController {
     if (this.fallback === undefined) {
       return undefined;
     }
-    // The fallback route behaves like it has a "/*" path. This is hidden from
-    // the public API; the `path` is there to return a valid RouteConfig. The
-    // match itself is done by hand rather than with a real `/*` pattern: a
-    // nested controller is handed its tail *without* a leading slash, which
-    // `/*` does not match, so a nested fallback matched nothing — empty
-    // params, no tail, and its own children never routed.
+    // Matched by hand, not with a real `/*` pattern: a nested controller gets
+    // its tail without a leading slash, which `/*` rejects. See #5.
     const {pathname} = location;
     const tail = pathname.startsWith('/') ? pathname.slice(1) : pathname;
     return {route: {...this.fallback, path: '/*'}, params: {0: tail}, tail};
@@ -562,26 +669,19 @@ export class Routes implements ReactiveController {
   }
 
   hostDisconnected() {
-    // Remove the listener hostConnected added. Without this a host that is
-    // disconnected and reconnected (a repeat() reorder, a tab swap) leaves the
-    // sibling controller's listener installed, so on the second connect it
-    // claims the re-dispatching controller as *its* child and the pair point
-    // at each other — a real `_childRoutes` cycle, which recursive walks turn
-    // into a stack overflow.
+    // Without this, a disconnected and reconnected host leaves a sibling's
+    // listener installed and the two claim each other as children: a
+    // `_childRoutes` cycle, which recursive walks turn into a stack overflow.
     this._host.removeEventListener(
       RoutesConnectedEvent.eventName,
       this._onRoutesConnected
     );
-    // When this child routes controller is disconnected because a parent
-    // outlet rendered a different template, disconnecting will ensure that
-    // this controller doesn't receive a tail match meant for another route.
     this._onDisconnect?.();
     this._parentRoutes = undefined;
   }
 
   private _onRoutesConnected = (e: RoutesConnectedEvent) => {
-    // Don't handle the event fired by this routes controller, which we get
-    // because we do this.dispatchEvent(...)
+    // Ignore our own event, which we receive because we dispatch on the host.
     if (e.routes === this) {
       return;
     }
@@ -598,18 +698,12 @@ export class Routes implements ReactiveController {
       }
     };
 
-    // A child that mounts under an existing tail match has to be caught up to
-    // it — it missed the propagation loop in goto() that ran before it existed.
-    // With no tail there is nothing to catch up to, and `_routeChild` then only
-    // supersedes, a no-op on a freshly mounted child.
+    // Catch up a child that mounted after goto()'s propagation loop ran.
     this._routeChild(childRoutes, this._currentTail);
   };
 }
 
-/**
- * This event is fired from Routes controllers when their host is connected to
- * announce the child route and potentially connect to a parent routes controller.
- */
+/** Announces a Routes controller to its parent when the host connects. */
 export class RoutesConnectedEvent extends Event {
   static readonly eventName = 'lit-routes-connected';
   readonly routes: Routes;