fix(router): nested unnamed include() routes match; dispatch matches through the route trie - #1128

devcorner: dc-t7 · dc-t26

Closes #1104
Closes #1107

Problem

#1104. With the trie live (every request in vite dev and production), the routes of an unnamed include() inside another unnamed include() answered 404, with no warning from the build, rango generate or the dev server. The same cause made a route behind a { name: "" } include render another module's handler, or 404 in production, when two included modules named a route alike (index).

#1107. dispatch from @rangojs/router/testing matched a router with no trie by URL pattern, while serveShellRequest and the real handler build the trie first. A router answered differently depending on what ran before: /api/items/ got a 308 on a fresh router and a 200 after serveShellRequest. A route only the trie gets wrong (the #1104 shape) passed in dispatch and 404'd in the app.

Cause of #1104: the hidden include name $prefix_N came from a counter whose value differs by realm. Build discovery produced $prefix_0.$prefix_0.login; lazy expansion at runtime produced $prefix_0.$prefix_1.login, because the counter snapshot is carried into lazy includes. find-match.ts then fell back silently.

Before and after

// urls.tsx
include("/", publicPatterns), // unnamed

// urls-public.tsx
export const publicPatterns = urls(({ include }) => [
  include("/", signInPatterns), // unnamed, nested
]);

// before: GET /login          -> 404 (dev and production), no warning
// after:  GET /login          -> the sign-in route

// path.json("/api/items", handler), no trailingSlash option
const res = await dispatch(router, { request: "/api/items/" });
// before: 308 -> /api/items on a fresh router, 200 after serveShellRequest
// after:  200 from the route, before and after serveShellRequest

End-to-end consumer example

An app mounts a public area and a sign-in area, both unnamed, and tests them in userland:

// urls.tsx
export const urlpatterns = urls(({ include, path }) => [
  include("/", publicPatterns), // unnamed
]);

// urls-public.tsx
export const publicPatterns = urls(({ include, path }) => [
  path("/", HomePage, { name: "home" }),
  include("/", signInPatterns), // unnamed, nested
]);

// urls-sign-in.tsx
export const signInPatterns = urls(({ path }) => [
  path("/login", LoginPage, { name: "login" }),
]);

// sign-in.test.ts
const router = createRouter({}).routes(urlpatterns);
const res = await dispatch(router, { request: "/login" });
expect(res.status).toBe(200); // was 404 in the app, and 200 here only because dispatch used the regex matcher

No source change is needed. The include("/", signInPatterns, { name: "" }) workaround keeps working.

Semantics

Code changes

• src/urls/include-helper.ts: hidden names come from tree position, not a counter. nextIncludePosition counts per handler run (keyed by scopePath, which no ancestor snapshot holds), so every run counts from 0 in every realm. A nested unnamed include is $prefix_0.$prefix_0; one behind a transparent include is $prefix_1_0.

  const index = nextIncludePosition(ctx.counters, ctx.scopePath);
  const hiddenSoFar = joinScopePath(ctx.hiddenScopePath, index);
  const nextSegment = hasExplicitName
    ? explicitName
    : `${INTERNAL_INCLUDE_SCOPE_PREFIX}${hiddenSoFar}`;

  Why here: it is the one place that allocates the name; deriving it from position makes build and runtime agree by construction. IncludeScopePosition rides on the DSL context and through TrackedInclude and LazyIncludeContext (server/context.ts, types/route-entry.ts, build/generate-manifest.ts).

• src/router/lazy-includes.ts: one resolveEntryPatterns for match-time expansion and loadManifest; replaces _lazyInflight and the providerResolutions WeakMap. Concurrent first hits share the import.

• src/router/find-match.ts: the dev tripwire (describeUnownedTrieRoute).

• src/testing/dispatch.ts, src/rsc/manifest-init.ts: dispatch calls ensureRouterTrie(router), which builds the trie unless the id has one from this router object. A NO_TRIE marker stops a zero-route router rebuilding on every dispatch. handler.ts is untouched: dev on Node gets tries pushed by router-discovery that no router object built, so the dispatch predicate would rebuild there.

• Docs: docs/internal/matching-and-lazy-discovery.md, async-includes.md, feature-map.md, docs/testing.md, skills/testing/response-routes.md.

Not applied: deriving includeScope from scopePath, because includeScope feeds shortCodes, which are segment ids.

Test plan

• src/router/__tests__/include-scope-names.test.ts (24 tests): build discovery and runtime expansion produce the same keys; dispatch serves every route through the dev and the production trie. 20 red without the fix.
• src/router/__tests__/find-match.test.ts: the dev throw names the route; red without the fix.
• src/testing/__tests__/dispatch.test.ts, async-include-dispatch.test.ts: trie built once per router; the NO_TRIE test failed with "expected 4 to be 2" before the marker.
• Userland, tests/cloudflare-basic/test/include-scope-dispatch.test.ts and dispatch-after-shell.rsc-test.tsx: both red without the fix; the second pins the 200-before-and-after answer.
• e2e packages/rangojs-router/e2e/include-scope.test.ts and tests/cloudflare-basic/e2e/include-scope.test.ts, each with a dev and a (production) describe. Router 115/115 (include-scope, route-resolution, semantic-matrix, include-middleware, optional-include), cloudflare-basic include-scope 4/4, dev and production, on the pre-rebase tree. Red was shown for cloudflare-basic dev only; the production counterparts were not run red.
• On the rebased tree (0.24.1): typecheck 16/16; test:unit:all router 8,733 passed (5 skipped, 6 todo), rsc 830 passed (2 expected fail), consumer suites 1, 3, 20, 25, 27, 27, 87 passed; lint 0 warnings; format clean; check:e2e-bucketing OK; check-bundle-guards green, router chunk 49,527 B against 49,536 B.
• CI runs e2e on the rebased tree.

Notes

• Hidden names can change with this upgrade. On-demand prerender entries are stored under the route name: an app that pins createRouter({ version }) and prerenders on demand under unnamed includes should bump version on upgrade. This is in the CHANGELOG entry.
• Headroom is 9 B under the 49,536 B router-chunk limit (main with fix(router): a clientUrls() layout() keeps its instance across navigations between its routes (#1124) #1125 is already near it).
• tools/generate-route-types.mjs does not exist on this base. When the gen-files PR (dc-t21) lands first, this branch adds fixture modules (urls/include-scope.tsx, pages/include-scope.tsx) and needs node tools/generate-route-types.mjs run and committed after the rebase. git status --porcelain | grep '\.gen\.ts' is empty now.
• The first dispatch per router runs every included urls() handler once more; tests counting handler or provider calls count from after it.