Make route order deterministic

src/router.ts

@@ -71,7 +71,7 @@ export class BaseFileSystemRouter extends EventTarget {
   }
 
   async buildRoutes(): Promise<RouteManifestEntry[]> {
-    for (const src of glob(this.glob())) {
+    for (const src of glob(this.glob()).sort()) {
       await this.addRoute(src);
     }
 

src/tree.ts

@@ -46,7 +46,7 @@ export function buildRouteTree(entries: readonly RouteManifestEntry[]): RouteTre
   }
 
   return [...entries]
-    .sort((a, b) => a.path.length - b.path.length)
+    .sort((a, b) => (a.path.length - b.path.length) || a.path.localeCompare(b.path))
     .reduce((routes: RouteTreeEntry[], route) => {
       processRoute(routes, route, route.path);
       return routes;

test/convention.spec.ts

@@ -226,4 +226,43 @@ describe("PageFileSystemRouter", () => {
 
     expect(routes.map(route => route.path)).toEqual(["/home"]);
   });
+
+  it("produces the manifest in a deterministic order across scans", async () => {
+    const dir = createRouteTree({
+      "index.tsx": "export default () => <h1>Home</h1>;",
+      "about.tsx": "export default () => <h1>About</h1>;",
+      "zebra.tsx": "export default () => <h1>Z</h1>;",
+      "blog/index.tsx": "export default () => <h1>Blog</h1>;",
+      "blog/[id].tsx": "export default () => <h1>Post</h1>;",
+      "docs/[...path].tsx": "export default () => <h1>Docs</h1>;",
+      "contact.tsx": "export default () => <h1>Contact</h1>;"
+    });
+
+    // Fresh router per scan — getRoutes() memoizes, so a new instance
+    // forces a real re-glob each time. Map to paths but do NOT .sort().
+    const scan = async () =>
+      (await new PageFileSystemRouter({ dir, extensions: ["tsx"] }).getRoutes())
+        .map(route => route.path);
+
+    const first = await scan();
+
+    // 1. Repeatable: N independent scans yield the same order.
+    for (let i = 0; i < 5; i++) {
+      expect(await scan()).toEqual(first);
+    }
+
+    // 2. Pin the exact order so the guarantee is explicit.
+    // The sort is on source file paths (lexicographic), so the order
+    // reflects that: about.tsx < blog/[id].tsx < blog/index.tsx <
+    // contact.tsx < docs/[...path].tsx < index.tsx < zebra.tsx.
+    expect(first).toEqual([
+      "/about",
+      "/blog/:id",
+      "/blog/",
+      "/contact",
+      "/docs/*path",
+      "/",
+      "/zebra"
+    ]);
+  });
 });

test/tree.spec.ts

@@ -52,4 +52,17 @@ describe("buildRouteTree", () => {
     expect(entries.map(e => e.path)).toEqual(paths);
     expect(entries.every(e => !("children" in e))).toBe(true);
   });
+
+  it("sorts equal-length paths deterministically", () => {
+    const tree = buildRouteTree([
+      entry("/zebra"),
+      entry("/about"),
+      entry("/alpha")
+    ]);
+
+    // All have the same path length, so the tie-breaker (localeCompare)
+    // guarantees a stable lexicographic order instead of relying on
+    // whatever order the glob happened to return.
+    expect(tree.map(node => node.path)).toEqual(["/about", "/alpha", "/zebra"]);
+  });
 });