filesystem-routing 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ryan Carniato
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,317 @@
+# filesystem-routing
+
+Router-neutral file-system routing.
+
+This package owns the *machinery* of file routing — scanning a directory,
+applying a filename convention and producing a neutral **route manifest** —
+while routers own the *shapes*: each router ships a small emission adapter
+that turns the manifest into its own route definitions, and each bundler ships
+a delivery adapter that materializes the manifest into code.
+
+| Piece | Owner |
+| --- | --- |
+| Scanning, filename convention, neutral route manifest | `filesystem-routing` |
+| Nesting + `(group)` stripping | `filesystem-routing/tree` |
+| Vite delivery (virtual module, HMR, code splitting, build inputs) | `filesystem-routing/vite` |
+| `RouteDefinition` emission | `@solidjs/router/fs` |
+| Request handling for `GET`/`POST` routes, middleware | `@solidjs/start` |
+
+Nothing here is Solid-specific: the core is bundler-agnostic — it never imports
+Vite — the Vite adapter is router-agnostic, and the conventions are the ones
+proven by SolidStart. The manifest is served from `virtual:file-routes`, or
+from whatever id you pass as `fileRoutes({ moduleId })`.
+
+## Usage with Solid Router and Vite
+
+```ts
+// vite.config.ts
+import { fileRoutes } from "filesystem-routing/vite";
+import { defineConfig } from "vite";
+import solid from "vite-plugin-solid";
+
+export default defineConfig({
+  // `extensions` makes vite-plugin-solid also compile the `?pick=` route
+  // modules this plugin emits (their ids end in a query string)
+  plugins: [solid({ extensions: [".jsx", ".tsx"] }), fileRoutes()]
+});
+```
+
+```tsx
+// src/app.tsx
+import { pageRoutes } from "virtual:file-routes";
+import { createRouter } from "@solidjs/router";
+import { fileRoutes } from "@solidjs/router/fs";
+
+const Router = createRouter({ routes: fileRoutes(pageRoutes) });
+
+export const App = () => <Router>{props => <>{props.children}</>}</Router>;
+```
+
+The emission adapter never imports the virtual module itself — the app does,
+so the adapter resolves without the plugin, custom `moduleId`s work, and
+nothing needs excluding from dependency prebundling.
+
+Route modules live in `src/routes` (configurable via `fileRoutes({ dir })`).
+A module is a page when it has a default export, and may export a `route`
+config object:
+
+```tsx
+// src/routes/blog/[id].tsx
+import type { RouteDefinition } from "@solidjs/router";
+
+export const route = {
+  preload: ({ params }) => loadPost(params.id)
+} satisfies RouteDefinition;
+
+export default function Post() {
+  return <h1>Post</h1>;
+}
+```
+
+## Filename conventions
+
+Two conventions ship in the box. Both produce the same neutral manifest and
+share the same module convention (default export is a page, `route` config
+export, `httpMethods` handlers), so they are equally capable — only the
+filenames differ.
+
+### Nested (`PageFileSystemRouter`, the default)
+
+The convention proven by SolidStart:
+
+| File | Path |
+| --- | --- |
+| `index.tsx` | `/` |
+| `about.tsx` | `/about` |
+| `blog/[id].tsx` | `/blog/:id` |
+| `blog/[[page]].tsx` | `/blog/:page?` |
+| `docs/[...path].tsx` | `/docs/*path` |
+| `(marketing)/about.tsx` | `/about`, nested in the `(marketing)` group |
+
+Nested layouts come from pairing a file with a directory: `blog.tsx` is the
+layout for everything in `blog/`.
+
+### Flat (`FlatFileSystemRouter`)
+
+The convention proven by Remix v2 and carried forward by React Router's
+`@react-router/fs-routes` — `.` delimiters instead of directories:
+
+| File | Path |
+| --- | --- |
+| `_index.tsx` | `/` |
+| `about.tsx` | `/about` |
+| `concerts.trending.tsx` | `/concerts/trending` |
+| `concerts.$city.tsx` | `/concerts/:city` |
+| `concerts.($page).tsx` | `/concerts/:page?` |
+| `files.$.tsx` | `/files/*splat` |
+| `_auth.login.tsx` | `/login`, nested in the `_auth.tsx` pathless layout |
+| `concerts_.mine.tsx` | `/concerts/mine`, escaping the `concerts.tsx` layout |
+| `[sitemap.xml].tsx` | `/sitemap.xml` — brackets escape special characters |
+
+`concerts.tsx` is the layout for every `concerts.*` file; a top-level folder
+routes through its `route.tsx` module and co-locates everything else in the
+folder without routing it. Pass the router to the plugin:
+
+```ts
+import { FlatFileSystemRouter } from "filesystem-routing";
+import { fileRoutes } from "filesystem-routing/vite";
+import { resolve } from "node:path";
+
+fileRoutes({
+  router: new FlatFileSystemRouter({
+    dir: resolve("src/routes"),
+    extensions: ["js", "jsx", "ts", "tsx"]
+  })
+});
+```
+
+Two departures from Remix: the catch-all param is named (`params.splat`
+rather than `params["*"]`), and optional *static* segments (`(en).about.tsx`)
+are rejected — the neutral pattern language has no representation for them.
+
+## API routes
+
+Route modules can answer requests as well as render. Turn on `httpMethods`
+(off by default — a client-only manifest has no use for handlers) and
+uppercase exports become request handlers:
+
+```ts
+// src/routes/api/posts/[id].ts
+export function GET(event) {
+  return Response.json(loadPost(event.params.id));
+}
+
+export function DELETE(event) {
+  deletePost(event.params.id);
+  return new Response(null, { status: 204 });
+}
+```
+
+The scanner turns each handler export into a lazy ref on the entry —
+`$GET: { src, pick: ["GET"] }`, `$DELETE: …` — with the same code splitting
+pages get:
+
+- A module with handlers but no default export routes without being a page:
+  `{ path: "/api/posts/:id", page: false, $GET, $DELETE }`.
+- A module can be both. A page with a `GET` export gets `$component` *and*
+  `$GET`, and handler exports are excluded from the component ref's picks, so
+  handler code never reaches the client bundle.
+- A lone `GET` also answers `HEAD`: a `$HEAD` ref aliasing the `GET` export
+  is added unless the module exports its own.
+- The recognized set is `HEAD`/`GET`/`POST`/`PUT`/`DELETE`/`PATCH`/`OPTIONS`;
+  pass an array instead of `true` to change it.
+
+This package stops at the manifest: it discovers handlers, it does not serve
+them. Dispatch is a few lines in whatever server consumes the manifest —
+match the URL, import the ref, call the export:
+
+```ts
+// any SSR handler or middleware
+import routes from "virtual:file-routes";
+
+async function handleApi(request: Request, entry, params) {
+  const ref = entry[`$${request.method}`];
+  if (!ref) return new Response(null, { status: 405 });
+  const handlers = await ref.import();
+  // a HEAD alias imports the GET handler
+  return (handlers[request.method] ?? handlers.GET)({ request, params });
+}
+```
+
+The handler's argument is whatever your server passes — the convention only
+dictates the export names. Frameworks typically enable `httpMethods` on the
+server environment's router only (SolidStart pairs it with `components:
+false` in SPA mode, so the server manifest routes requests without shipping
+page modules) — see the per-environment `routers` option below.
+
+## Custom conventions
+
+Conventions plug in at two independent seams, so a custom scheme picks the
+level it needs:
+
+- **`toPath`** — the filename convention: maps a route file (relative to
+  `dir`, extension stripped, e.g. `/blog/[id]`) to a route path in the
+  neutral pattern language (`:param`, `:param?`, `*rest`, `(group)`), or
+  `undefined` to skip the file. Layout nesting is encoded in the paths
+  themselves: `buildRouteTree` nests entries by path prefix (a layout at
+  `/blog` wraps a page at `/blog/`), and `(group)` segments nest without
+  contributing URL — which is also how pathless layouts and layout escapes
+  are expressed.
+- **`toRoute`** — the module convention: maps a source file to a manifest
+  entry, deciding what makes a file a route and which refs it carries. The
+  built-in one analyzes exports (default export, `route` config, HTTP
+  handlers); a custom one can key off anything.
+
+Pass either as config for one-off tweaks:
+
+```ts
+import { PageFileSystemRouter } from "filesystem-routing";
+import { fileRoutes } from "filesystem-routing/vite";
+
+fileRoutes({
+  toPath: routeFile => (routeFile.endsWith(".page") ? routeFile.slice(0, -5) : undefined)
+});
+```
+
+Or subclass for a full scheme — `FlatFileSystemRouter` is the model: it
+extends `PageFileSystemRouter`, overrides only `toPath`, and everything else
+(scanning, watching, module analysis, the tree, type generation) is
+inherited. A convention that also changes what a route module *is* overrides
+`toRoute`; a convention that changes what gets scanned overrides `glob()` on
+`BaseFileSystemRouter`.
+
+## The manifest seam
+
+The scanner produces flat `RouteManifestEntry` objects:
+
+```ts
+{
+  path: "/blog/:id",           // neutral pattern language
+  page: true,
+  $component: { src, pick },   // lazy module ref → code-split dynamic import
+  $$route: { src, pick }       // eager module ref → static import
+}
+```
+
+The Vite adapter serializes the manifest into the virtual module, turning
+`$`-prefixed refs into dynamic imports and `$$`-prefixed refs into static
+imports, each tree-shaken down to the picked exports. It serves two views of
+the same entries:
+
+```ts
+import routes, { pageRoutes } from "virtual:file-routes";
+```
+
+`routes` is the flat manifest; `pageRoutes` is the page entries nested by path
+with `(group)` segments stripped, so emission adapters don't each reimplement
+the tree (`buildRouteTree` from `filesystem-routing/tree` is the same
+function, for consumers holding only a flat manifest). An emission adapter is
+a function taking manifest entries and returning the router's shape — see
+`fileRoutes` in `@solidjs/router/fs` for Solid Router's, a ~30 line adapter
+other routers can mirror. Adapters take the manifest as an argument rather
+than importing the virtual module, so they work standalone and with custom
+module ids.
+
+Add `/// <reference types="filesystem-routing/types" />` to type the import.
+
+### Keeping path-derived types alive
+
+A manifest is a runtime value, so a router that derives types from its route
+table gets nothing from it — `@solidjs/router`'s `RoutePaths` degrades to `any`
+the moment the table is a `RouteDefinition[]` rather than a tuple. Turn on
+`types` and the plugin writes a declaration in which the manifest *is* a
+literal tuple, regenerating it as routes come and go:
+
+```ts
+fileRoutes({ types: "file-routes.d.ts" })
+```
+
+Reference the generated file instead of `filesystem-routing/types` — it is
+self-contained, and two declarations of the same module conflict. Emission
+adapters then have to preserve the tuple on the way through, which means a
+mapping typed over its input rather than a plain `.map`:
+
+```ts
+declare function toRoutes<const T extends readonly Entry[]>(
+  entries: T
+): { [K in keyof T]: RouteFrom<T[K]> };
+```
+
+Frameworks with several Vite environments can serve a different router (and
+convention) per environment, and have the plugin take every route module as a
+build entry for the browser one:
+
+```ts
+fileRoutes({
+  routers: {
+    // the browser routes and renders
+    client: new PageFileSystemRouter({ dir, extensions }),
+    // the server also answers `GET`/`POST` exports, and in SPA mode routes
+    // without shipping components
+    ssr: new PageFileSystemRouter({ dir, extensions, httpMethods: true, components: ssr })
+  },
+  buildInputs: "client"
+});
+```
+
+| Option | What it does |
+| --- | --- |
+| `httpMethods` | emit `$GET`, `$POST`, … refs for uppercase handler exports; a module with handlers but no default export routes without being a page |
+| `components` | set `false` to route without emitting `$component` refs, keeping page modules out of that environment's bundle |
+| `buildInputs` | environments whose build takes every code-split route module as an entry |
+| `moduleId` | the id the manifest is served from |
+| `optimizeDepsExclude` | escape hatch for packages that import the virtual module, kept out of dep prebundling (defaults to `[]`) |
+| `types` | write a declaration typing the manifest as a literal tuple, kept in step with the route directory |
+
+## Credits
+
+The design comes from [Vinxi](https://github.com/nksaraf/vinxi)'s file-system
+router by Nikhil Saraf, which powered SolidStart through 1.x: the
+`BaseFileSystemRouter` with pluggable `toPath`/`toRoute`, and above all the
+insight that the manifest should carry inert module refs — `$`-prefixed keys
+becoming dynamic imports, `$$`-prefixed keys becoming static ones — so any
+router and any bundler can meet at the same seam. This package extracts that
+approach into a standalone library, adding the nested tree view, the flat
+convention, and literal-tuple type generation. The filename conventions are
+the ones proven by [SolidStart](https://github.com/solidjs/solid-start) and
+[Remix](https://remix.run) v2.

package/dist/analyze.d.ts

@@ -0,0 +1,16 @@
+import { type StaticExportEntry } from "oxc-parser";
+export type { StaticExportEntry };
+/**
+ * Analyze a route module's static exports.
+ *
+ * This is the compiler-shaped slice of file routing: it reports what a module
+ * exports without knowing what a route is. It is kept behind its own seam so
+ * a compiler that already performs export analysis can provide it instead.
+ */
+export declare function analyzeModule(src: string): StaticExportEntry[];
+export declare function getExportName(entry: StaticExportEntry): string;
+/**
+ * Returns the export name only when it is backed by a same-named local
+ * binding, i.e. it can be re-picked from the module without renaming.
+ */
+export declare function getLocalExportName(entry: StaticExportEntry): string | undefined;

package/dist/analyze.js

@@ -0,0 +1,29 @@
+import fs from "node:fs";
+import { parseSync } from "oxc-parser";
+/**
+ * Analyze a route module's static exports.
+ *
+ * This is the compiler-shaped slice of file routing: it reports what a module
+ * exports without knowing what a route is. It is kept behind its own seam so
+ * a compiler that already performs export analysis can provide it instead.
+ */
+export function analyzeModule(src) {
+    const result = parseSync(src, fs.readFileSync(src, "utf-8"), { lang: "tsx" });
+    const error = result.errors[0];
+    if (error)
+        throw new SyntaxError(`Failed to parse ${src}:\n${error.codeframe || error.message}`);
+    return result.module.staticExports.flatMap(({ entries }) => entries.filter(entry => !entry.isType && entry.exportName.kind !== "None"));
+}
+export function getExportName(entry) {
+    return entry.exportName.name ?? "default";
+}
+/**
+ * Returns the export name only when it is backed by a same-named local
+ * binding, i.e. it can be re-picked from the module without renaming.
+ */
+export function getLocalExportName(entry) {
+    const name = getExportName(entry);
+    if (name === "default")
+        return;
+    return name === (entry.localName.name ?? entry.importName.name ?? name) ? name : undefined;
+}

package/dist/convention.d.ts

@@ -0,0 +1,45 @@
+import type { RouteManifestEntry } from "./manifest.ts";
+import { BaseFileSystemRouter, type FileSystemRouterConfig } from "./router.ts";
+/**
+ * The filename convention proven by SolidStart:
+ * - `index` files map to their directory's path
+ * - `[param]` maps to `:param`
+ * - `[[param]]` maps to an optional `:param?`
+ * - `[...rest]` maps to a catch-all `*rest`
+ * - `(group)` segments are retained for emission adapters to nest and strip
+ */
+export declare function routePathFromFile(routeFile: string): string;
+/**
+ * The HTTP methods a route module may export as a request handler. Enabled
+ * per-router via `httpMethods`; frameworks that do not serve requests from
+ * route modules (a client manifest, a static site) leave it off.
+ */
+export declare const HTTP_METHODS: readonly ["HEAD", "GET", "POST", "PUT", "DELETE", "PATCH", "OPTIONS"];
+export interface PageFileSystemRouterConfig extends FileSystemRouterConfig {
+    /**
+     * Emit `$component` refs for pages. Set to `false` for manifests that
+     * route without rendering — a server manifest in SPA mode, where the
+     * client owns every component — so page modules stay out of that bundle.
+     * Defaults to `true`.
+     */
+    components?: boolean;
+    /**
+     * Treat these uppercase exports as request handlers, emitting a `$GET`,
+     * `$POST`, … ref for each (and a `$HEAD` alias for a lone `GET`). A module
+     * with handlers but no default export is a route without being a page.
+     * Pass `true` for the standard set. Defaults to `false`.
+     */
+    httpMethods?: boolean | readonly string[];
+}
+/**
+ * The module convention proven by SolidStart: a route module is a page when
+ * it has a default export, may export a `route` config object, and — when
+ * `httpMethods` is on — may export `GET`, `POST`, … request handlers.
+ * `.md`/`.mdx` files are always pages.
+ */
+export declare class PageFileSystemRouter extends BaseFileSystemRouter {
+    config: PageFileSystemRouterConfig;
+    constructor(config: PageFileSystemRouterConfig);
+    toPath(src: string): string | undefined;
+    toRoute(src: string): RouteManifestEntry | undefined;
+}

package/dist/convention.js

@@ -0,0 +1,118 @@
+import { analyzeModule, getExportName, getLocalExportName } from "./analyze.js";
+import { BaseFileSystemRouter, cleanPath } from "./router.js";
+/**
+ * The filename convention proven by SolidStart:
+ * - `index` files map to their directory's path
+ * - `[param]` maps to `:param`
+ * - `[[param]]` maps to an optional `:param?`
+ * - `[...rest]` maps to a catch-all `*rest`
+ * - `(group)` segments are retained for emission adapters to nest and strip
+ */
+export function routePathFromFile(routeFile) {
+    const routePath = routeFile
+        // remove the initial slash
+        .slice(1)
+        .replace(/index$/, "")
+        .replace(/\[([^/]+)\]/g, (_, m) => {
+        if (m.length > 3 && m.startsWith("...")) {
+            return `*${m.slice(3)}`;
+        }
+        if (m.length > 2 && m.startsWith("[") && m.endsWith("]")) {
+            return `:${m.slice(1, -1)}?`;
+        }
+        return `:${m}`;
+    });
+    return routePath?.length > 0 ? `/${routePath}` : "/";
+}
+/**
+ * The HTTP methods a route module may export as a request handler. Enabled
+ * per-router via `httpMethods`; frameworks that do not serve requests from
+ * route modules (a client manifest, a static site) leave it off.
+ */
+export const HTTP_METHODS = ["HEAD", "GET", "POST", "PUT", "DELETE", "PATCH", "OPTIONS"];
+function httpMethodsOf(config) {
+    if (!config.httpMethods)
+        return [];
+    return config.httpMethods === true ? HTTP_METHODS : config.httpMethods;
+}
+function createHandlerRefs(src, exports, methods) {
+    const handlers = {};
+    for (const method of methods) {
+        if (!exports.includes(method))
+            continue;
+        handlers[`$${method}`] = { src, pick: [method] };
+    }
+    // A `GET` handler answers `HEAD` unless the module handles it itself.
+    if (handlers.$GET && !handlers.$HEAD && methods.includes("HEAD")) {
+        handlers.$HEAD = { src, pick: ["GET"] };
+    }
+    return handlers;
+}
+/**
+ * The module convention proven by SolidStart: a route module is a page when
+ * it has a default export, may export a `route` config object, and — when
+ * `httpMethods` is on — may export `GET`, `POST`, … request handlers.
+ * `.md`/`.mdx` files are always pages.
+ */
+export class PageFileSystemRouter extends BaseFileSystemRouter {
+    constructor(config) {
+        super(config);
+    }
+    toPath(src) {
+        if (this.config.toPath)
+            return super.toPath(src);
+        return routePathFromFile(cleanPath(src, this.config));
+    }
+    toRoute(src) {
+        if (this.config.toRoute)
+            return super.toRoute(src);
+        const path = this.toPath(src);
+        if (path === undefined)
+            return;
+        const components = this.config.components ?? true;
+        if (src.endsWith(".md") || src.endsWith(".mdx")) {
+            return {
+                page: true,
+                $component: components
+                    ? {
+                        src: src,
+                        pick: ["$css"]
+                    }
+                    : undefined,
+                $$route: undefined,
+                path
+            };
+        }
+        const methods = httpMethodsOf(this.config);
+        const exports = analyzeModule(src);
+        const exportNames = exports.map(getExportName);
+        const localExportNames = exports.map(getLocalExportName).filter(name => name !== undefined);
+        const hasDefault = exportNames.includes("default");
+        const hasRouteConfig = exportNames.includes("route");
+        const handlers = createHandlerRefs(src, exportNames, methods);
+        const hasHandlers = Object.keys(handlers).length > 0;
+        if (hasDefault || hasHandlers) {
+            return {
+                page: hasDefault,
+                $component: components && hasDefault
+                    ? {
+                        src: src,
+                        pick: [
+                            ...localExportNames.filter(name => name !== "route" && !methods.includes(name)),
+                            "default",
+                            "$css"
+                        ]
+                    }
+                    : undefined,
+                $$route: hasRouteConfig
+                    ? {
+                        src: src,
+                        pick: ["route"]
+                    }
+                    : undefined,
+                ...handlers,
+                path
+            };
+        }
+    }
+}

package/dist/flat.d.ts

@@ -0,0 +1,16 @@
+import { PageFileSystemRouter } from "./convention.ts";
+/**
+ * Maps a flat route file (relative to the route dir, extension stripped,
+ * e.g. `/concerts.$city`) to a route path in the neutral pattern language,
+ * or `undefined` for co-located files that are not routes.
+ */
+export declare function flatRoutePathFromFile(routeFile: string): string | undefined;
+/**
+ * `PageFileSystemRouter` with the flat filename convention. The module
+ * convention is inherited unchanged — default export is a page, `route`
+ * config export, `httpMethods` handlers, `components: false` — so the two
+ * conventions are equally capable; only the filenames differ.
+ */
+export declare class FlatFileSystemRouter extends PageFileSystemRouter {
+    toPath(src: string): string | undefined;
+}

package/dist/flat.js

@@ -0,0 +1,102 @@
+import { PageFileSystemRouter } from "./convention.js";
+import { cleanPath } from "./router.js";
+/** Splits a flat route name on unescaped `.`, resolving `[...]` escapes. */
+function parseSegments(name) {
+    const segments = [[]];
+    let inEscape = false;
+    for (const char of name) {
+        if (char === "[" && !inEscape) {
+            inEscape = true;
+        }
+        else if (char === "]" && inEscape) {
+            inEscape = false;
+        }
+        else if (char === "." && !inEscape) {
+            segments.push([]);
+        }
+        else {
+            segments[segments.length - 1].push({ char, escaped: inEscape });
+        }
+    }
+    return segments;
+}
+const text = (chars) => chars.map(c => c.char).join("");
+const unescapedAt = (chars, index, char) => chars.at(index)?.char === char && !chars.at(index).escaped;
+function interpretSegment(segment, isFinal) {
+    // `_index` routes to its parent's path (the leading `_` must be literal)
+    if (isFinal && unescapedAt(segment, 0, "_") && text(segment) === "_index") {
+        return { escapesLayout: false };
+    }
+    let chars = segment;
+    let escapesLayout = false;
+    if (chars.length > 1 && unescapedAt(chars, -1, "_")) {
+        chars = chars.slice(0, -1);
+        escapesLayout = true;
+    }
+    // a pathless layout becomes a group segment the tree nests by and strips
+    if (unescapedAt(chars, 0, "_")) {
+        return { text: `(${text(chars)})`, escapesLayout };
+    }
+    let optional = false;
+    if (chars.length > 2 && unescapedAt(chars, 0, "(") && unescapedAt(chars, -1, ")")) {
+        chars = chars.slice(1, -1);
+        optional = true;
+    }
+    if (unescapedAt(chars, 0, "$")) {
+        const param = text(chars.slice(1));
+        if (param === "")
+            return { text: "*splat", escapesLayout };
+        return { text: `:${param}${optional ? "?" : ""}`, escapesLayout };
+    }
+    if (optional) {
+        throw new Error(`Optional static segments have no neutral representation: (${text(chars)})`);
+    }
+    return { text: text(chars), escapesLayout };
+}
+/**
+ * Maps a flat route file (relative to the route dir, extension stripped,
+ * e.g. `/concerts.$city`) to a route path in the neutral pattern language,
+ * or `undefined` for co-located files that are not routes.
+ */
+export function flatRoutePathFromFile(routeFile) {
+    const parts = routeFile.slice(1).split("/");
+    // a top-level folder routes through its `route` module only
+    if (parts.length === 2 && parts[1] !== "route")
+        return undefined;
+    if (parts.length > 2)
+        return undefined;
+    const segments = parseSegments(parts[0]);
+    const path = [];
+    let index = false;
+    for (const [i, segment] of segments.entries()) {
+        const flat = interpretSegment(segment, i === segments.length - 1);
+        if (flat.text === undefined) {
+            index = true;
+            break;
+        }
+        // a synthetic group breaks `buildRouteTree`'s prefix match with the
+        // parent layout while stripping back out of the URL
+        if (flat.escapesLayout)
+            path.push(`(${flat.text}_)`);
+        path.push(flat.text);
+    }
+    // an index route takes its parent's path plus a trailing slash, the same
+    // shape the nested convention gives `index` files, so the tree nests it
+    // under the layout that shares its path
+    if (index)
+        return `/${path.map(segment => segment + "/").join("")}`;
+    return path.length > 0 ? `/${path.join("/")}` : "/";
+}
+/**
+ * `PageFileSystemRouter` with the flat filename convention. The module
+ * convention is inherited unchanged — default export is a page, `route`
+ * config export, `httpMethods` handlers, `components: false` — so the two
+ * conventions are equally capable; only the filenames differ.
+ */
+export class FlatFileSystemRouter extends PageFileSystemRouter {
+    toPath(src) {
+        if (this.config.toPath)
+            return super.toPath(src);
+        return flatRoutePathFromFile(cleanPath(src, this.config));
+    }
+}

package/dist/index.d.ts

@@ -0,0 +1,7 @@
+export { analyzeModule, getExportName, getLocalExportName } from "./analyze.ts";
+export type { StaticExportEntry } from "./analyze.ts";
+export type { ModuleRef, RouteManifestEntry } from "./manifest.ts";
+export { BaseFileSystemRouter, cleanPath, glob, normalizePath, type FileSystemRouterConfig } from "./router.ts";
+export { HTTP_METHODS, PageFileSystemRouter, routePathFromFile, type PageFileSystemRouterConfig } from "./convention.ts";
+export { FlatFileSystemRouter, flatRoutePathFromFile } from "./flat.ts";
+export { buildRouteTree, stripRouteGroups, type RouteTreeEntry } from "./tree.ts";