lit-navigation-router 0.5.0 → 0.6.0

package/development/routes.js

@@ -6,11 +6,8 @@
  * Modifications Copyright 2026 VanLandingham Labs, same license. See NOTICE.md.
  */
 /**
- * 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) => {
     const hashIndex = path.indexOf('#');
@@ -25,10 +22,8 @@ const parseLocation = (path) => {
 };
 /** Re-attaches `search` and `hash` to a pathname. Inverse of `parseLocation`. */
 const formatLocation = (pathname, { search, hash }) => pathname + (search === '' ? '' : `?${search}`) + (hash === '' ? '' : `#${hash}`);
-// 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();
 const isPatternConfig = (route) => route.pattern !== undefined;
 const getPattern = (route) => {
@@ -42,26 +37,16 @@ const getPattern = (route) => {
     return pattern;
 };
 /**
- * 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, params) => {
     if (!TRAILING_WILDCARD.test(getPattern(route).pathname)) {
@@ -69,79 +54,201 @@ const tailOf = (route, params) => {
     }
     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);
         }
     }
     return tailIndex < 0 ? undefined : params[String(tailIndex)];
 };
+/**
+ * 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, name) => {
+    let i = 0;
+    let positional = 0;
+    const takeModifier = () => {
+        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) => {
+        const nodes = [];
+        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) => 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, params, tailIndex, missing) => {
+    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, params, name) => {
+    const nodes = parsePattern(pattern, name);
+    const missing = [];
+    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.
  */
 export class Routes {
     _host;
-    /*
-     * 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 = [];
     /**
-     * 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;
-    /*
-     * The current set of child Routes controllers. These are connected via
-     * the routes-connected event.
-     */
     _childRoutes = [];
     _parentRoutes;
-    /*
-     * 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(). */
     _gotoSeq = 0;
     _currentPathname;
     _currentTail;
-    /**
-     * 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. */
     _currentSearch = '';
     _currentHash = '';
     _currentRoute;
     _currentParams = {};
-    /**
-     * 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)`.
     _onDisconnect;
@@ -165,38 +272,77 @@ export class Routes {
         return (this._parentRoutes?.link() ?? '') + pathname;
     }
     /**
-     * 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, params = {}) {
+        let root = this;
+        while (root._parentRoutes !== undefined) {
+            root = root._parentRoutes;
+        }
+        const found = [];
+        const visit = (routes, seen) => {
+            // 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, options) {
         // TODO (justinfagnani): handle absolute vs relative paths separately.
         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;
         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 {
@@ -208,17 +354,14 @@ export class Routes {
             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 =
@@ -229,24 +372,12 @@ export class Routes {
         this._currentTail = tail;
         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);
         }
@@ -265,26 +396,12 @@ export class Routes {
         return this._currentParams;
     }
     /**
-     * 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.
      */
     _routeChild(child, tail) {
         if (tail === undefined) {
@@ -305,42 +422,25 @@ export class Routes {
             });
         });
     }
-    /**
-     * 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. */
     _supersede(seen = new Set()) {
-        // 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.
      */
     _constrainsHash(seen = new Set()) {
         // Cycle guard, matching `_supersede`; see the note there.
@@ -352,34 +452,24 @@ export class Routes {
             this._childRoutes.some((c) => c._constrainsHash(seen)));
     }
     /**
-     * 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) {
-        // 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.
      */
     _match(location) {
         for (const route of this.routes) {
@@ -388,10 +478,8 @@ export class Routes {
                 const params = {
                     ...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)) {
@@ -405,12 +493,8 @@ export class Routes {
         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 };
@@ -422,22 +506,15 @@ export class Routes {
         this._onDisconnect = event.onDisconnect;
     }
     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;
     }
     _onRoutesConnected = (e) => {
-        // 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;
         }
@@ -451,17 +528,11 @@ export class Routes {
                 this._childRoutes.splice(index, 1);
             }
         };
-        // 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 eventName = 'lit-routes-connected';
     routes;