feat: a folder's own URL lands on its first page

[gitKrystan]

Stacked on gitkrystan/collections (universal-ember#366), because it touches Folder — the type that branch renames. Retarget at main once universal-ember#366 lands.

The gap

/Group/sub-folder names a real place in the docs but no document of its own, so visiting one renders the error page. Readers type and link these URLs by hand; on one large internal docs site, 5 of 9 broken links found by a link-crawl were exactly this shape.

Resolution normalizes only the .md extension:

// browser/utils.ts
export function samePagePath(a: string, b: string): boolean {
  return equalsIgnoreCase(a.replace(/\.md$/i, ''), b.replace(/\.md$/i, ''));
}

So /Group/sub-folder/page resolves (extensionless page URLs work), while /Group/sub-folder matches nothing. handlePotentialIndexVisit already redirects a group's own URL to its first page — this applies the same rule one level down.

Approach

Redirect rather than resolve. Rendering the index page at the folder URL would give one page two URLs, and the nav's active state compares currentURL via samePagePath, so the folder URL would highlight nothing. Redirecting also makes folder roots and group roots behave identically.

The target is the folder's first page. Sorting has already hoisted index.md to the top of the folder that holds it, so that is a folder's index page when it has one, and its first ordered page when it doesn't — one rule, both cases, and the same rule group.list[0] encodes at the group root.

Two subtleties, both called out in comments:

• The new branch runs only after a page lookup misses. An ordinary page visit lands on the wildcard's index too, with the page as the wildcard param, and must be left alone — the invariant the existing comment in handlePotentialIndexVisit describes.
• That page lookup is manifest-wide, not findByPath. findByPath searches currentGroup, which derives from router.currentURL — during a transition's beforeModel that still names the previous page.

And the mount translation: the wildcard holds only the part of the URL below the mount, so a mount with a path of its own needs its group put back on the front. A scoped mount names it in the binding; an unscoped nested mount takes it as its path (the route above the wildcard); a top-level mount's wildcard already carries it. The unscoped-nested case is the one I got wrong first — /demos/components was looked up as /components.

API

One method on the docs service, landingForFolder(appRelativePath), and two pure helpers in browser/utils.ts (findFolder, firstPageIn). Nothing existing changed shape.

Tests

App	Covers
docs-app	folder with an index (/authoring → /authoring/index), folder without (/development → /development/rendering-pages), trailing slash, casing, a page's URL is left alone, a path that is neither still errors
custom-root-url	the rootURL-doubling hazard, alongside the existing group-root guard for it; trailing slash; casing; page-not-redirected
multiple-docs-routes	a scoped mount (/help/getting-started, mount space ≠ manifest space) and an unscoped nested mount (/demos/components)

Results on this branch:

• multiple-docs-routes — 18/18 pass
• virtual-routes-only — 5/5 pass
• docs-app via the dev server (/tests/?skipAllLinks) — 102 tests, 371 assertions, 0 failed, 5 skipped
• custom-root-url — 12 pass, 4 fail; markdown-only — 1 pass, 1 fail

Those 5 failures are pre-existing on gitkrystan/collections. I verified by stashing this change, rebuilding, and re-running both apps: identical failures. They all come from the Home group's nav link becoming / instead of /Home, which those apps' nav-active-state and crawl snapshots still expect — worth a fix on universal-ember#366 before it merges.

One caveat: a built testem ci run of docs-app also showed 11 failures, all 120–180s timeouts in <ComponentSignature> / <HelperSignature> / <ModifierSignature> / gitRef. The dev-server run of the same suite is fully green and none of those modules touch routing, so I read them as environmental — but I did not baseline that particular run, since it takes ~20 minutes.

🤖 Generated with Claude Code

[gitKrystan]

Superseded by universal-ember#370 — rebased onto upstream main (this was stacked on the unmerged universal-ember#366) and renamed to the PageTree vocabulary that universal-ember#368 settled on.