@junejs/server 1.0.0-dev.42 → 1.0.0-dev.45

package/src/dev.ts

@@ -19,20 +19,41 @@ import { findGlobalCss, processCssCached, invalidateCss } from "./css";
 export type DevServerOptions = {
   appDir: string;
   port?: number;
+  // The address to bind. Default 127.0.0.1: the dev server is reachable from this
+  // machine only (MCP: "when running locally, servers SHOULD bind only to
+  // localhost"). "0.0.0.0" opens it to the LAN — `june dev --host`.
+  hostname?: string;
   host?: JuneHost;
 };
 
-export type DevServer = ServeHandle & { url: string };
+// The Host names a dev server answers /mcp and /api for (#308): localhost and its
+// subdomains, plus IP literals (always allowed — rebinding needs a domain name),
+// plus a named --host and whatever the config allows.
+// The URL to print and return: localhost for loopback or a wildcard bind (it
+// answers there too), else the one address bound — nothing listens on loopback then.
+export function devUrl(hostname: string, port: number): string {
+  if (["127.0.0.1", "0.0.0.0", "::", "localhost"].includes(hostname)) return `http://localhost:${port}`;
+  return `http://${hostname.includes(":") ? `[${hostname}]` : hostname}:${port}`;
+}
+
+export function devAllowedHosts(configured: readonly string[] | undefined, hostname: string): string[] {
+  const hosts = new Set(["localhost", ".localhost", ...(configured ?? [])]);
+  if (!/^[\d.]+$|:/.test(hostname)) hosts.add(hostname.toLowerCase()); // a name, not 0.0.0.0 / an IP
+  return [...hosts];
+}
+
+// stop() also shuts the app down (its agent runtime, #317); await it to know that's done.
+export type DevServer = Omit<ServeHandle, "stop"> & { url: string; stop(force?: boolean): Promise<void> };
 
 // A taken default port must not be a dead end in dev — walk forward until a
 // port binds (the Vite convention). Probed with node:net, which both hosts
 // implement, so the host interface stays untouched.
-async function findFreePort(start: number, tries = 20): Promise<number> {
+async function findFreePort(start: number, hostname: string, tries = 20): Promise<number> {
   for (let p = start; p < start + tries; p++) {
     const free = await new Promise<boolean>((resolve) => {
       const probe = createNetServer();
       probe.once("error", () => resolve(false));
-      probe.listen(p, () => probe.close(() => resolve(true)));
+      probe.listen(p, hostname, () => probe.close(() => resolve(true)));
     });
     if (free) return p;
   }
@@ -42,10 +63,13 @@ async function findFreePort(start: number, tries = 20): Promise<number> {
 export async function startDevServer({
   appDir,
   port = 3000,
+  hostname = "127.0.0.1",
   host = defaultHost,
 }: DevServerOptions): Promise<DevServer> {
   await installAsyncContext();
-  const config = await loadJuneConfig(appDir);
+  const loaded = await loadJuneConfig(appDir);
+  // The DNS-rebinding check (#308): a local server is exactly what rebinding targets.
+  const config = { ...loaded, agent: { ...loaded.agent, allowedHosts: devAllowedHosts(loaded.agent?.allowedHosts, hostname) } };
 
   // Apply pending migrations before serving — dev auto-applies the SAFE ones; a
   // destructive one is reported and skipped (the server still starts, but the
@@ -57,7 +81,7 @@ export async function startDevServer({
   const app = createApp({ appDir, config });
   await app.warmup();
 
-  const freePort = await findFreePort(port);
+  const freePort = await findFreePort(port, hostname);
   if (freePort !== port) console.log(`[june] port ${port} is taken → using ${freePort}`);
   port = freePort;
 
@@ -65,6 +89,7 @@ export async function startDevServer({
   // dev/built parity) never sees it. See dev-reload.ts.
   const handle = host.serve(withLiveReload((req) => app.fetch(req)), {
     port,
+    hostname,
     earlyHints: () => app.earlyHints(),
   });
 
@@ -87,7 +112,15 @@ export async function startDevServer({
     void processCssCached(appDir).catch(() => {});
   }
 
-  const url = `http://localhost:${handle.port}`;
-  console.log(`june dev → ${url}  (host: ${host.name})`);
-  return { ...handle, url };
+  const url = devUrl(hostname, handle.port);
+  const lan = hostname === "127.0.0.1" ? "" : `  · listening on ${hostname}`;
+  console.log(`june dev → ${url}  (host: ${host.name})${lan}`);
+  return {
+    ...handle,
+    url,
+    async stop(force?: boolean) {
+      handle.stop(force);
+      await app.close();
+    },
+  };
 }

package/src/host.ts

@@ -42,7 +42,8 @@ export interface JuneHost {
   readonly name: "bun" | "node";
   serve(
     handler: (req: Request) => Promise<Response>,
-    opts: { port: number; earlyHints?: () => string[] },
+    // hostname: the address to bind. Absent = all interfaces (production, containers).
+    opts: { port: number; hostname?: string; earlyHints?: () => string[] },
   ): ServeHandle;
   // Spawn a module in a child runtime (the react-server Flight renderer, which
   // must run under a different module-resolution condition). Phase 4 supersedes
@@ -63,7 +64,7 @@ function bunHost(): JuneHost {
       // idleTimeout 0: Bun's 10s default kills quiet long-lived responses —
       // the dev live-reload SSE most visibly (the browser then reconnects,
       // reads it as a server restart, and reloads the page every 10s).
-      const server = Bun.serve({ port: opts.port, fetch: handler, idleTimeout: 0 });
+      const server = Bun.serve({ port: opts.port, hostname: opts.hostname, fetch: handler, idleTimeout: 0 });
       return { port: server.port ?? opts.port, stop: (force) => void server.stop(force) };
     },
     spawnModule(entry, args, opts) {
@@ -125,7 +126,7 @@ function nodeHost(): JuneHost {
           res.end("Internal Server Error");
         }
       });
-      server.listen(opts.port);
+      server.listen(opts.port, opts.hostname);
       return {
         get port() {
           const addr = server.address();

package/src/manifest.ts

@@ -63,6 +63,7 @@ export async function buildManifest(appRoot: string): Promise<WorkerManifest> {
   const routes: Record<string, BrandedRoute> = {};
   const dynamicRoutes: Array<{ pattern: string; def: BrandedRoute }> = [];
   const resourceRoutes: Array<{ pattern: string; handler: ResourceHandler }> = [];
+  const generatedRoutes = scanned.filter((r) => r.generated).map((r) => r.path);
   const layoutChains: Record<string, LayoutComponent[]> = {};
   const layoutBoundaries: Record<string, { index: number; key: string }> = {};
   const loadings: Record<string, LoadingComponent> = {};
@@ -115,6 +116,7 @@ export async function buildManifest(appRoot: string): Promise<WorkerManifest> {
     routes,
     dynamicRoutes,
     resourceRoutes,
+    ...(generatedRoutes.length ? { generatedRoutes } : {}),
     layoutChains,
     layoutBoundaries,
     loadings,

package/src/pipeline.ts

@@ -48,9 +48,10 @@ import {
   siteSkill,
   sitemapXml,
 } from "@junejs/core/discovery";
-import { mcpHandler, mcpServerIdentity, mcpTools } from "@junejs/core/mcp";
+import { mcpForbidden, mcpHandler, mcpServerIdentity, mcpTools, originRejection } from "@junejs/core/mcp";
 import {
   apiActionId,
+  apiForbidden,
   apiHandler,
   apiNamespaceResponse,
   isApiNamespace,
@@ -854,6 +855,14 @@ export function createPipeline(cfg: PipelineConfig): Pipeline {
     }
   }
 
+  // Which browsers may call /mcp and /api (#308) — the config's allowlists.
+  const originPolicy = { allowedOrigins: agent.allowedOrigins, allowedHosts: agent.allowedHosts };
+  // Only a POST runs an action on /mcp or /api; any other method is a CORS
+  // preflight or a 405. A preflight carries no credentials, so a cookie-reading
+  // resolver could throw on it — never resolve identity for one.
+  const callerIdentity = async (request: Request) =>
+    request.method === "POST" && cfg.identity ? await cfg.identity(request) : undefined;
+
   async function handleRequest(request: Request): Promise<Response> {
       const url = new URL(request.url);
 
@@ -864,11 +873,16 @@ export function createPipeline(cfg: PipelineConfig): Pipeline {
         // ambient `db` is the SAME resource the UI uses, and — via cfg.identity —
         // the same principal: requiresPrincipal actions and per-call connection
         // auth are live on this surface. ctx carries identity only — not resources.
-        const identity = cfg.identity ? await cfg.identity(request) : undefined;
+        // The origin policy first: a refused browser call must not reach the
+        // identity resolver (its I/O, or a throw that would turn 403 into 500).
+        const refused = originRejection(request, originPolicy);
+        if (refused !== undefined) return mcpForbidden(refused);
+        const identity = await callerIdentity(request);
         return mcpHandler(
           request,
           { request, ...identity },
           mcpServerIdentity(url.origin, { site: docConfig.site, agent }),
+          originPolicy,
         );
       }
       // The REST projection of the same actions: POST /api/<id> dispatches through
@@ -887,8 +901,10 @@ export function createPipeline(cfg: PipelineConfig): Pipeline {
         }
         const actionId = apiActionId(url.pathname);
         if (actionId) {
-          const identity = cfg.identity ? await cfg.identity(request) : undefined;
-          return apiHandler(request, actionId, { request, ...identity });
+          const refused = originRejection(request, originPolicy);
+          if (refused !== undefined) return apiForbidden(request, refused);
+          const identity = await callerIdentity(request);
+          return apiHandler(request, actionId, { request, ...identity }, originPolicy);
         }
       }
       // The server card is read cross-origin by browser-based MCP clients; its

package/src/route-rank.ts

@@ -0,0 +1,60 @@
+// Route precedence — the ONE ranking both resolvers use (#312). The dev matcher
+// (router.ts, matchRouteTree) walks the app tree trying each level's children in
+// this order; the built worker (worker.ts) cannot walk a tree, so it sorts its
+// flat route table with compareRoutePatterns and takes the first regex match.
+// For patterns that both match a URL, the depth-first walk and the sorted table
+// pick the same winner: the first segment where two patterns differ decides.
+//
+// Worker-safe: no node:* imports.
+
+export type SegmentKind = "static" | "param" | "optional" | "catchAll" | "optionalCatchAll";
+
+// The one segment grammar: a param name is an identifier ([A-Za-z_][A-Za-z0-9_]*).
+// Anything else in brackets (`[1]`, `[foo-bar]`, `[slug].png`) is a STATIC
+// segment named literally, in dev, in the ranking and in the worker's regex.
+const DYNAMIC = /^\[(\[)?(\.\.\.)?([A-Za-z_][A-Za-z0-9_]*)\](\])?$/;
+
+export function parseSegment(segment: string): { kind: SegmentKind; name?: string } {
+  const m = segment.match(DYNAMIC);
+  // Brackets must pair: `[[x]]` or `[x]`, never `[[x]` / `[x]]`.
+  if (!m || !!m[1] !== !!m[4]) return { kind: "static" };
+  const optional = !!m[1];
+  const catchAll = !!m[2];
+  const kind: SegmentKind = catchAll
+    ? optional ? "optionalCatchAll" : "catchAll"
+    : optional ? "optional" : "param";
+  return { kind, name: m[3] };
+}
+
+const RANK: Record<SegmentKind, number> = { static: 0, param: 1, optional: 2, catchAll: 3, optionalCatchAll: 4 };
+
+// Per-segment rank, most specific first: static, [param], [[param]], [...rest],
+// [[...rest]]. Optional sits after its required form, so `[slug]` answers
+// before `[[slug]]` when a segment is present.
+export function segmentRank(segment: string): number {
+  return RANK[parseSegment(segment).kind];
+}
+
+// Sibling order within one directory level: by rank, then by name so a tie
+// (two [param] dirs) resolves the same on every filesystem.
+export function compareSegments(a: string, b: string): number {
+  return segmentRank(a) - segmentRank(b) || (a < b ? -1 : a > b ? 1 : 0);
+}
+
+// Order two file-route patterns ("/docs/[[...path]]", "/feed.xml") by
+// precedence. The first differing segment decides; a pattern that ends there
+// beats one that continues, since only absent optional segments can follow a
+// match that already consumed the URL (dev checks a directory's own page before
+// descending into its optional children).
+export function compareRoutePatterns(a: string, b: string): number {
+  const as = a.split("/").filter(Boolean);
+  const bs = b.split("/").filter(Boolean);
+  for (let i = 0; i < Math.max(as.length, bs.length); i++) {
+    const x = as[i];
+    const y = bs[i];
+    if (x === undefined) return -1;
+    if (y === undefined) return 1;
+    if (x !== y) return compareSegments(x, y);
+  }
+  return 0;
+}

package/src/route-scan.ts

@@ -8,6 +8,8 @@ import { existsSync } from "node:fs";
 import { readdir } from "node:fs/promises";
 import { basename, join, relative, sep } from "node:path";
 
+import { parseSegment } from "./route-rank";
+
 // The segment layout CHAIN root→leaf: every directory level (route groups
 // included) may contribute a layout.* that wraps routes below it.
 export type RouteEntry = {
@@ -15,6 +17,7 @@ export type RouteEntry = {
   file: string;
   dynamic: boolean;
   resource?: boolean; // a route.* resource route (raw-Response handler), not a page
+  generated?: boolean; // scanned from .june/routes/ — ranks after every app/ route, as in dev
   layouts: string[];
   loading?: string; // nearest loading.tsx up the tree → streaming Suspense fallback
 };
@@ -77,8 +80,82 @@ export async function scanAppRoutes(appRoot: string): Promise<RouteEntry[]> {
   const juneRoutesDir = join(appRoot, ".june", "routes");
   const appRoutes = await scanRoutes(appDir);
   const frameworkRoutes = existsSync(juneRoutesDir) ? await scanRoutes(juneRoutesDir) : [];
+  const problems = routeProblems([appRoutes, frameworkRoutes], appRoot);
+  if (problems) throw new Error(problems);
   const appPaths = new Set(appRoutes.map((r) => r.path));
-  return [...appRoutes, ...frameworkRoutes.filter((r) => !appPaths.has(r.path))].sort((a, b) =>
+  const generated = frameworkRoutes
+    .filter((r) => !appPaths.has(r.path))
+    .map((r) => ({ ...r, generated: true }));
+  return [...appRoutes, ...generated].sort((a, b) =>
     a.path.localeCompare(b.path),
   );
 }
+
+// Two route files in ONE tree that resolve to the same URL: `(a)/about/page.tsx`
+// and `(b)/about/page.tsx` (groups vanish from the URL), or `page.tsx` next to
+// `index.tsx`. Pages and resource routes are counted apart — a page and a
+// route.ts at the same path are allowed, in one dir or across groups (the page
+// wins). No winner is defined for the rest: dev
+// would pick by group order and the worker by scan order, so the build refuses
+// them and dev reports them (#316).
+export function routeConflicts(routes: RouteEntry[]): Array<{ path: string; files: string[] }> {
+  const byKey = new Map<string, { path: string; files: string[] }>();
+  for (const r of routes) {
+    const key = `${r.resource ? "route" : "page"} ${r.path}`;
+    const hit = byKey.get(key);
+    if (hit) hit.files.push(r.file);
+    else byKey.set(key, { path: r.path, files: [r.file] });
+  }
+  return [...byKey.values()]
+    .filter((c) => c.files.length > 1)
+    .map((c) => ({ path: c.path, files: c.files.sort() }))
+    .sort((a, b) => a.path.localeCompare(b.path));
+}
+
+// An optional or catch-all segment ([[x]], [...x], [[...x]]) must END the route
+// path (#315, the Next.js rule, opinionated). Mid-path there is no behavior to
+// keep: dev never matched past a catch-all nor skipped a mid-path [[x]], while
+// the worker's regex did both. A (group) after it is not a URL segment, so it's
+// fine. Returns the offending routes, path-sorted.
+const ENDS_PATH = new Set(["optional", "catchAll", "optionalCatchAll"]);
+const beforeLast = (path: string) => path.split("/").filter(Boolean).slice(0, -1).map((s) => parseSegment(s).kind);
+
+export function misplacedSegments(routes: RouteEntry[]): RouteEntry[] {
+  return routes
+    .filter((r) => beforeLast(r.path).some((k) => ENDS_PATH.has(k)))
+    .sort((a, b) => a.path.localeCompare(b.path) || a.file.localeCompare(b.file));
+}
+
+// Every route-table problem the build refuses and dev reports, as one message
+// (null when there are none). Each tree (app/, .june/routes/) is checked on its
+// own: the same path in both is not a conflict — app/ wins.
+export function routeProblems(trees: RouteEntry[][], appRoot: string): string | null {
+  const rel = (f: string) => relative(appRoot, f).split(sep).join("/");
+  const sections: string[] = [];
+
+  const conflicts = trees.flatMap(routeConflicts);
+  if (conflicts.length) {
+    sections.push(
+      "[june] more than one route file resolves to the same path — keep one per path:\n" +
+        conflicts.map((c) => `  ${c.path}: ${c.files.map(rel).join(", ")}`).join("\n"),
+    );
+  }
+
+  const misplaced = trees.flatMap(misplacedSegments);
+  if (misplaced.length) {
+    const lines = misplaced.map((r) => `  ${r.path}: ${rel(r.file)}`);
+    // Developers (and models) read [[x]] the SvelteKit way, skippable anywhere;
+    // say so when a single optional is the culprit, and point at the real tool.
+    if (misplaced.some((r) => beforeLast(r.path).includes("optional"))) {
+      lines.push(
+        "  Unlike SvelteKit, June does not skip a [[param]] mid-path. For a locale prefix, set i18n.locales in june.config.ts instead of a [[lang]] directory.",
+      );
+    }
+    sections.push(
+      "[june] an optional or catch-all segment must be the last segment of a route path — nothing may follow it:\n" +
+        lines.join("\n"),
+    );
+  }
+
+  return sections.length ? sections.join("\n") : null;
+}

package/src/router.ts

@@ -6,6 +6,8 @@ import { existsSync } from "node:fs";
 import { readdir } from "node:fs/promises";
 import { join, relative, sep } from "node:path";
 
+import { compareSegments, parseSegment } from "./route-rank";
+
 export type RouteMatch = {
   file: string;
   params: Record<string, string>;
@@ -87,13 +89,13 @@ function isSpecialFile(file: string) {
 }
 
 const isRouteGroup = (name: string) => /^\(.+\)$/.test(name);
-const isParamDir = (name: string) => /^\[([A-Za-z_][A-Za-z0-9_]*)\]$/.test(name);
+const isParamDir = (name: string) => parseSegment(name).kind === "param";
 // [[slug]] / [[...slug]] — match like their required forms, and ALSO match the
 // segment being absent (the param is then simply missing from ctx.params).
-const isOptionalDir = (name: string) => /^\[\[([A-Za-z_][A-Za-z0-9_]*)\]\]$/.test(name);
-const isOptionalCatchAllDir = (name: string) => /^\[\[\.\.\.([A-Za-z_][A-Za-z0-9_]*)\]\]$/.test(name);
-const isCatchAllDir = (name: string) => /^\[\.\.\.([A-Za-z_][A-Za-z0-9_]*)\]$/.test(name);
-const paramName = (name: string) => name.replace(/^\[+(\.\.\.)?|\]+$/g, "");
+const isOptionalDir = (name: string) => parseSegment(name).kind === "optional";
+const isOptionalCatchAllDir = (name: string) => parseSegment(name).kind === "optionalCatchAll";
+const isCatchAllDir = (name: string) => parseSegment(name).kind === "catchAll";
+const paramName = (name: string) => parseSegment(name).name!;
 
 type DirEntry = { name: string; dir: boolean };
 
@@ -147,8 +149,12 @@ function routePath(appDir: string, file: string) {
 }
 
 // Recursive-descent matcher over the app directory. Priority at every level:
-// exact static segment > [param] > [...catchAll]; route groups `(name)` descend
-// without consuming a URL segment; `_`-prefixed entries never participate.
+// exact static segment > [param] > [...catchAll], required before optional, ties
+// by name (route-rank.ts — the built worker sorts its route table by the same
+// ranking); `_`-prefixed entries never participate. Route groups `(name)` are
+// invisible in the URL, so they are invisible to ranking too: a group's children
+// compete as siblings of the level the group sits in (a grouped `[slug]` never
+// shadows a static sibling), while the group still contributes its layout.
 // Returns the page file, accumulated params (catch-all joins with "/"), and the
 // chain of segments (with their special files) from the app root to the page.
 export async function matchRouteTree(
@@ -158,85 +164,96 @@ export async function matchRouteTree(
 ): Promise<RouteTreeMatch | null> {
   const urlSegments = pathname.split("/").filter(Boolean).map(decodeURIComponent);
 
+  // One URL level = this dir plus every route group under it (groups nest), each
+  // with the segment chain down to it: the dir first, then groups in name order.
+  type Level = { dir: string; entries: DirEntry[]; segments: SegmentMatch[] };
+  async function levelAt(dir: string, chain: SegmentMatch[]): Promise<Level[]> {
+    // Ranked, not readdir order, so the pick is the same on every filesystem.
+    const entries = (await listDir(dir)).sort((a, b) => compareSegments(a.name, b.name));
+    const segments = [...chain, segmentAt(dir, entries)];
+    const levels: Level[] = [{ dir, entries, segments }];
+    for (const e of entries) {
+      if (e.dir && isRouteGroup(e.name)) levels.push(...(await levelAt(join(dir, e.name), segments)));
+    }
+    return levels;
+  }
+
+  // A URL level can span several real dirs: `(a)/blog` and `(b)/blog` are both
+  // `/blog`, so they descend TOGETHER — otherwise (a)/blog/[slug] would answer
+  // /blog/about before (b)/blog/about was ever seen.
+  type Node = { dir: string; chain: SegmentMatch[] };
+
   async function descend(
-    dir: string,
+    nodes: Node[],
     rest: string[],
     params: Record<string, string>,
-    chain: SegmentMatch[],
   ): Promise<RouteTreeMatch | null> {
-    const entries = await listDir(dir);
-    const segments = [...chain, segmentAt(dir, entries)];
+    const levels = (await Promise.all(nodes.map((n) => levelAt(n.dir, n.chain)))).flat();
 
-    // Terminal: URL consumed → find the page (or resource route) in this dir.
+    // Terminal: URL consumed → find the page at this level, groups included,
+    // and only then a resource route: a page beats a route.ts at the same path
+    // even when the two sit in different groups (the worker ranks them so).
     if (rest.length === 0) {
-      const page =
-        fileFor(entries, dir, "page") ??
-        fileFor(entries, dir, "index") ??
-        fileFor(entries, dir, "route");
-      if (page) return { file: page, params, segments };
-    } else if (!options.pageConvention) {
+      for (const base of [["page", "index"], ["route"]]) {
+        for (const { dir: d, entries, segments } of levels) {
+          const file = base.map((b) => fileFor(entries, d, b)).find(Boolean);
+          if (file) return { file, params, segments };
+        }
+      }
+    } else if (!options.pageConvention && rest.length === 1) {
       // Legacy flat convention: a non-special leaf FILE names the final segment
       // (examples/rsc: about.tsx → /about). Only valid for the last segment.
-      if (rest.length === 1) {
-        const leaf = fileFor(entries, dir, rest[0]!);
-        if (leaf && !isSpecialFile(leaf) && !isPageFile(leaf)) {
-          return { file: leaf, params, segments };
-        }
+      for (const { dir: d, entries, segments } of levels) {
+        const leaf = fileFor(entries, d, rest[0]!);
+        if (leaf && !isSpecialFile(leaf) && !isPageFile(leaf)) return { file: leaf, params, segments };
       }
     }
 
-    // Route groups: try descending into every (group) without consuming URL.
-    for (const e of entries) {
-      if (!e.dir || !isRouteGroup(e.name)) continue;
-      const hit = await descend(join(dir, e.name), rest, params, segments);
-      if (hit) return hit;
+    // Every child dir at this level, groups flattened and same names merged, in
+    // rank order.
+    const children = new Map<string, Node[]>();
+    for (const lv of levels) {
+      for (const e of lv.entries) {
+        if (!e.dir || isRouteGroup(e.name)) continue;
+        const node = { dir: join(lv.dir, e.name), chain: lv.segments };
+        const same = children.get(e.name);
+        if (same) same.push(node);
+        else children.set(e.name, [node]);
+      }
     }
+    const names = [...children.keys()].sort(compareSegments);
 
     if (rest.length === 0) {
       // Optional segments match ABSENCE too: descend without consuming and
       // without setting the param.
-      for (const e of entries) {
-        if (!e.dir || !(isOptionalDir(e.name) || isOptionalCatchAllDir(e.name))) continue;
-        const hit = await descend(join(dir, e.name), [], params, segments);
+      for (const name of names) {
+        if (!(isOptionalDir(name) || isOptionalCatchAllDir(name))) continue;
+        const hit = await descend(children.get(name)!, [], params);
         if (hit) return hit;
       }
       return null;
     }
     const [head, ...tail] = rest as [string, ...string[]];
 
-    // 1) exact static dir
-    const exact = entries.find((e) => e.dir && e.name === head);
-    if (exact) {
-      const hit = await descend(join(dir, head), tail, params, segments);
-      if (hit) return hit;
-    }
-    // 2) [param] and [[param]] dirs consume one segment
-    for (const e of entries) {
-      if (!e.dir || !(isParamDir(e.name) || isOptionalDir(e.name))) continue;
-      const hit = await descend(
-        join(dir, e.name),
-        tail,
-        { ...params, [paramName(e.name)]: head },
-        segments,
-      );
-      if (hit) return hit;
-    }
-    // 3) [...catchAll] and [[...catchAll]] dirs consume everything remaining
-    for (const e of entries) {
-      if (!e.dir || !(isCatchAllDir(e.name) || isOptionalCatchAllDir(e.name))) continue;
-      const hit = await descend(
-        join(dir, e.name),
-        [],
-        { ...params, [paramName(e.name)]: rest.join("/") },
-        segments,
-      );
+    for (const name of names) {
+      const into = children.get(name)!;
+      let hit: RouteTreeMatch | null = null;
+      if (isParamDir(name) || isOptionalDir(name)) {
+        // [param] and [[param]] consume one segment
+        hit = await descend(into, tail, { ...params, [paramName(name)]: head });
+      } else if (isCatchAllDir(name) || isOptionalCatchAllDir(name)) {
+        // [...catchAll] and [[...catchAll]] consume everything remaining
+        hit = await descend(into, [], { ...params, [paramName(name)]: rest.join("/") });
+      } else if (name === head) {
+        hit = await descend(into, tail, params); // exact static dir
+      }
       if (hit) return hit;
     }
 
     return null;
   }
 
-  return descend(appDir, urlSegments, {}, []);
+  return descend([{ dir: appDir, chain: [] }], urlSegments, {});
 }
 
 // 404 path: walk the longest matchable STATIC prefix of the URL collecting