fix(router): dev/prod matching stability + lazy-include fixes - #541

Problem

An "extreme" review of the render pipeline, route matching, and lazy include() discovery — aimed at proving dev/production matching is stable for v1 — surfaced one consumer-observable matching bug, an incomplete nested-include prefix fix, a structural dev/prod drift hazard, and a set of cold-start lazy-include redundancies (one fixed, the rest deferred).

The headline consumer bug: a catch-all route path("/files/*") with no /files index 308-redirected /files to the wrong path /file. The trie matcher never matched a wildcard at its own bare prefix, so matching fell through to the regex fallback, whose no-config trailing-slash branch computed "/files".slice(0, -1) → /file. Identical in dev and production.

Two trie-construction code paths (dev rebuilds at request time; prod serializes at build time) were kept in sync by hand — a latent dev/prod divergence with no test pinning their equality. And a lazy-include performance audit confirmed lazy-by-default is the correct design (unmatched includes never run; warm requests run zero handlers), but found dev/Cloudflare lacked the match-time precomputed shortcut production already had.

What a consumer sees differently

Wildcard bare-prefix (the redirect bug)

export const urlpatterns = urls(({ path }) => [
  path("/files/*", FilesPage, { name: "files" }), // no "/files" index route
]);

A static index still wins over the wildcard at the same prefix (/files → files.index if defined).

Nested include under a trailing-slash prefix

urls(({ include }) => [
  include("/parent/", parentPatterns), // trailing slash
]);
// parentPatterns: include("/child", childPatterns) -> path("/leaf", ...)

Before, the nested entry got staticPrefix === "/parent//child" (double slash), which the trie's sp (/parent/child) could never match — silently forcing every request to that subtree onto the regex fallback. After, the join is normalized (matching include()/runWithPrefixes) so /parent/child/leaf matches via the trie like every other route.

Cold-start performance (no behavior change)

Dev/Cloudflare leaf includes now take the same match-time precomputed shortcut production already had (first-request handler runs 2 → 1). Warm requests run zero handlers in both modes. (Reducing the remaining once-per-sibling-route handler runs is deferred — see Notes/LP1.)

Matching semantics (trie is canonical; the regex path is a should-not-happen fallback)

Code changes

Two commits:

fix(router): stabilize dev/prod matching + unify trie construction

• trie-matching.ts — walkTrie/tryTrieMatch match a wildcard at the bare prefix with * === "" (C1).
• pattern-matching.ts — new shared joinPrefix(); remove dead ancestry field.
• lazy-includes.ts, router.ts — nested-include joins route through joinPrefix (C5).
• find-match.ts — cache hit returns a clone with independent params (C7); dev-only regex-fallback warning (R3); drop unused import (R5); remove dead ancestry (R4).
• build/route-trie.ts + new build/prefix-tree-utils.ts — one shared buildPerRouterTrie(manifest) used by both dev (manifest-init.ts) and prod (discover-routers.ts); pure prefix-tree walks moved out of vite/ so runtime can import them (R1/R2). Removes the dev/prod drift hazard.

fix(router): complete nested-include prefix normalization; precompute dev leaf includes

• lazy-includes.ts + manifest.ts — joinPrefix now also normalizes the prefix the lazy handler runs under (not just the nested-placeholder staticPrefix), so a nested include under a trailing-slash parent registers normalized patterns into entry.routes/reverse()/EntryData.pattern/mountPath (completes C5).
• manifest-init.ts — dev precomputes leaf-include entries via flattenLeafEntries, so dev takes the production match-time shortcut (LP2/C8).
• manifest.ts — the manifest cache stays keyed by routeKey. An attempted handler-identity key was reverted: loadManifest builds a manifest pruned to forRoute=routeKey (path-helper.ts skips siblings), so dropping routeKey makes alternating siblings thrash (LP1 — see Notes).
• docs — sync README.md, feature-map.md (buildPerRouterTrie), feature-file-map.md (build/prefix-tree-utils.ts).

Findings, evidence, and the deferred items are tracked in docs/internal/matching-stability-review.md.

Test plan

• Unit — 3373 pass + 6 todo (184 files). New: trie-regex-parity.test.ts (the two matchers agree on the stable surface; known divergences documented), dev-prod-trie-parity.test.ts (dev rebuilt trie === prod serialized trie, modulo debug-only leaf.a), find-match.test.ts (cache clone, recompute, MAX_LAZY_ITERATIONS), lazy-include-perf.test.ts (instruments handler-exec counts; proves laziness; pins LP2/C8; it.todo for LP1/LP3/LP4). Regressions: C1 (trie), C5 (nested-include staticPrefix and registered route pattern), C7 (cache clone).
• e2e dev + production — route-resolution (dev 18 / prod 10) and navigation incl. semantic-matrix, intercepts, actions, use-cache (dev 175 / prod 97).
• typecheck, oxlint (0/0), oxfmt, build-router.

Notes / call-outs

• Trailing slash is already complete and configurable — per-path path(..., { trailingSlash }) and per-include include(..., { trailingSlash }), with never/always/ignore. The trie honors the explicit modes and the trailing-slash-config e2e proves they behave identically in dev and production. The only nuance (M3 in the doc): the trie keeps the explicit mode but not the pattern-implicit slash (path("/foo/")), so with no explicit mode the never-reached regex fallback would canonicalize while the trie serves both. This is consistent across dev/prod (the trie is the live matcher) and configurable, so it's a documented non-issue, not a v1 decision — adding pattern-implicit canonicalization to the trie is optional future polish.
• Deferred future work (tracked as it.todo + a sentinel test): LP1 — an include with M routes runs its handler once per route on cold start (loadManifest prunes to forRoute, cache keyed by routeKey); running it once per include needs an unpruned-cache + prune-on-read design (a handler-identity key thrashes — verified, reverted). LP3 — a nested / precomputed-miss include runs its handler twice on the first request (match + render); the match-time build is discarded. LP4 — a cold document request runs each handler twice across the isSSR=false/true resolves (dropping isSSR is unsafe — it changes the tree). All are cold-start-only and amortized (each cached after first); a timing benchmark is the suggested next step before deciding if any is worth the needs-design change.
• Multi-router note (M2): the build-vs-runtime mountIndex difference only feeds the debug-only leaf.a ancestry (never read in the match/render path), so it is not a correctness bug — captured in the doc.