@solidjs/router 2.0.0-next.26 → 2.0.0-next.28

package/README.md

@@ -10,7 +10,7 @@
 
 </div>
 
-**Solid Router** brings fine-grained reactivity to route navigation. Routes are config objects — the single source of truth for matching *and* types — and the router upgrades HTML's own interaction verbs instead of wrapping them: `<a href={path}>` and `<form action={action}>` carry typed, URL-addressable values on real platform elements, intercepted by delegation, decorated with a shared attribute vocabulary, and fully functional without JavaScript.
+**Solid Router** brings fine-grained reactivity to route navigation. Routes are config objects — the single source of truth for matching _and_ types — and the router upgrades HTML's own interaction verbs instead of wrapping them: `<a href={path}>` and `<form action={action}>` carry typed, URL-addressable values on real platform elements, intercepted by delegation, decorated with a shared attribute vocabulary, and fully functional without JavaScript.
 
 Explore the official [documentation](https://docs.solidjs.com/solid-router) for detailed guides and examples.
 
@@ -36,6 +36,7 @@ Explore the official [documentation](https://docs.solidjs.com/solid-router) for
   - [Multiple Paths](#multiple-paths)
   - [Nested Routes](#nested-routes)
   - [Lazy Route Subtrees](#lazy-route-subtrees)
+  - [Server Component Routes (experimental)](#server-component-routes-experimental)
   - [File-System Routes](#file-system-routes)
 - [Typed Paths](#typed-paths)
 - [Links](#links)
@@ -89,7 +90,13 @@ When a tree is composed across files (feature subtrees), wrap the extracted arra
 ```tsx
 // features/admin/routes.ts
 export const adminRoutes = defineRoutes([
-  { path: "/admin", component: Admin, children: [/* ... */] }
+  {
+    path: "/admin",
+    component: Admin,
+    children: [
+      /* ... */
+    ]
+  }
 ]);
 
 // app/router.ts
@@ -138,19 +145,19 @@ The API splits across two surfaces, and the line between them is precise: **coul
 
 The instance is shared — one module-level object serving every mount, every request, every test. It is deliberately non-stateful (on the server there are many "current locations" at once), so it carries only the app's static routing vocabulary. Hooks read the live session from context.
 
-| Instance — facts about the *app* | Hooks — facts about the *session* |
-| --- | --- |
-| `paths` — how to spell URLs | `useLocation`, `useParams` — where am I |
-| `match(url)` — how would a URL match | `useNavigate`, `usePreloadRoute` — move / warm |
-| `routes`, `config` — what exists | `useIsRouting`, `useRouteMatches`, `useSearchParams` — live state |
+| Instance — facts about the _app_     | Hooks — facts about the _session_                                 |
+| ------------------------------------ | ----------------------------------------------------------------- |
+| `paths` — how to spell URLs          | `useLocation`, `useParams` — where am I                           |
+| `match(url)` — how would a URL match | `useNavigate`, `usePreloadRoute` — move / warm                    |
+| `routes`, `config` — what exists     | `useIsRouting`, `useRouteMatches`, `useSearchParams` — live state |
 
 They compose as noun and verb — the instance supplies a typed URL, the hook acts on the current session:
 
 ```tsx
 const navigate = useNavigate();
-navigate(paths.users(2));                 // verb(noun)
+navigate(paths.users(2)); // verb(noun)
 
-const params = useParams(paths.users);    // hook, typed by the instance
+const params = useParams(paths.users); // hook, typed by the instance
 ```
 
 **Hooks are the default; import the router only when you need typed URLs or matching outside a render.** Components that only read their session (params, location, string-path navigation) never need the instance — which also means component files don't form import cycles with the router module that references them in its config.
@@ -159,17 +166,17 @@ const params = useParams(paths.users);    // hook, typed by the instance
 
 A route definition supports:
 
-| key            | type                                    | description                                                        |
-| -------------- | --------------------------------------- | ------------------------------------------------------------------ |
-| `path`         | `string \| string[]`                    | Path partial for this route segment                                |
-| `component`    | `Component`                             | Component rendered for the matched segment                         |
+| key            | type                                                         | description                                                                     |
+| -------------- | ------------------------------------------------------------ | ------------------------------------------------------------------------------- |
+| `path`         | `string \| string[]`                                         | Path partial for this route segment                                             |
+| `component`    | `Component`                                                  | Component rendered for the matched segment                                      |
 | `children`     | `RouteDefinition \| RouteDefinition[] \| () => Promise<...>` | Nested route definitions, or a thunk for a [lazy subtree](#lazy-route-subtrees) |
-| `preload`      | `RoutePreloadFunc`                      | Called on preload intent (hover/focus) and navigation              |
-| `matchFilters` | `MatchFilters`                          | Additional constraints for matching parameters                     |
-| `search`       | `StandardSchemaV1`                      | Search-param validator; its types flow into `paths` and hooks      |
-| `info`         | `Record<string, any>`                   | Arbitrary metadata, readable via `useRouteMatches`                 |
+| `preload`      | `RoutePreloadFunc`                                           | Called on preload intent (hover/focus) and navigation                           |
+| `matchFilters` | `MatchFilters`                                               | Additional constraints for matching parameters                                  |
+| `search`       | `StandardSchemaV1`                                           | Search-param validator; its types flow into `paths` and hooks                   |
+| `info`         | `Record<string, any>`                                        | Arbitrary metadata, readable via `useRouteMatches`                              |
 
-The tree is **immutable and there is one router per app** — that's what makes `paths` and the typed hooks truthful, it lets matching compile once and be shared by every mount, request, and `match()` call, and it means delegation, link state, and preloading all have a single owner. Compose large apps by spreading subtrees into the config (see `defineRoutes` above); mounting a router inside another router is not supported (nested `<Routes>` has been gone since 0.10) and warns in development. Sections whose *code* shouldn't load up front are [lazy route subtrees](#lazy-route-subtrees) — still one tree, still typed.
+The tree is **immutable and there is one router per app** — that's what makes `paths` and the typed hooks truthful, it lets matching compile once and be shared by every mount, request, and `match()` call, and it means delegation, link state, and preloading all have a single owner. Compose large apps by spreading subtrees into the config (see `defineRoutes` above); mounting a router inside another router is not supported (nested `<Routes>` has been gone since 0.10) and warns in development. Sections whose _code_ shouldn't load up front are [lazy route subtrees](#lazy-route-subtrees) — still one tree, still typed.
 
 ### Dynamic Routes
 
@@ -204,8 +211,8 @@ const story = defineRoute({
   preload: ({ params }) => getStory(params.id), // params.id: string
   component: props => (
     <Story
-      id={props.params.id}    // string — the pattern guarantees it
-      tab={props.params.tab}  // string | undefined — optional param
+      id={props.params.id} // string — the pattern guarantees it
+      tab={props.params.tab} // string | undefined — optional param
     />
   )
 });
@@ -242,8 +249,8 @@ Each parameter can be validated with a `MatchFilter` — an enum array, a regex,
 import { int, type MatchFilters } from "@solidjs/router";
 
 const filters: MatchFilters = {
-  parent: ["mom", "dad"],                                    // enum values
-  id: /^\d+$/,                                               // only numbers
+  parent: ["mom", "dad"], // enum values
+  id: /^\d+$/, // only numbers
   withHtmlExtension: (v: string) => v.length > 5 && v.endsWith(".html")
 };
 
@@ -254,7 +261,7 @@ const routes = defineRoutes([
 
 So `/users/mom/123/contact.html` matches, while `/users/aunt/123/contact.html` (invalid `parent`) and `/users/mom/me/contact.html` (non-numeric `id`) don't.
 
-The built-in `int` filter is *typed*: it constrains matching to integers at runtime and types the param as `number` at `paths` callsites:
+The built-in `int` filter is _typed_: it constrains matching to integers at runtime and types the param as `number` at `paths` callsites:
 
 ```tsx
 { path: "/users/:id", matchFilters: { id: int }, component: User }
@@ -362,6 +369,64 @@ The import only fires when something needs the subtree — hovering a link into
 
 Resolution is cached per thunk and append-only: the tree never changes shape after a subtree lands, it just gets more specific. Keep thunks deterministic — `() => import(...)` — rather than switching tables on runtime state.
 
+### Server Component Routes (experimental)
+
+Solid's experimental [server components](https://github.com/solidjs/solid/blob/main/documentation/solid-2.0/11-server-components.md) are `"use server"` functions that return a component. `serverRouteComponent` takes a `query` over one and uses it as a route's `component` directly — the router owns the URL → call translation a client wrapper used to spell out:
+
+```tsx
+// story.tsx — the source owns its key
+import { query, type ServerRouteArgs } from "@solidjs/router";
+
+export const getStory = query(async ({ params }: ServerRouteArgs<{ id: string }>) => {
+  "use server";
+  const story = await db.stories.get(params.id);
+  return props => (
+    <article>
+      <h1>{story.title}</h1>
+      {props.children}
+    </article>
+  );
+}, "story");
+
+// routes.ts
+defineRoute({ path: "/stories/:id", component: serverRouteComponent(getStory) });
+```
+
+The source is called with **derived** arguments, not a live location — the call's `(function, arguments)` address keys both the query cache and the frame store, so the args name exactly what the route depends on:
+
+- `params`: the params this route's pattern (and its ancestors') declares — never a child's, so a layout does not refetch when a leaf param changes. `defineRoute` checks them against the pattern.
+- `search`: the validated output of the route's [`search` schema](#typed-search-params), only when one is declared. Otherwise `undefined`, and the route never tracks the query string.
+
+A route view is route-shaped on purpose — the address stays stable and `defineRoute` can check its params against the pattern — which means it is only callable as a route. When the same server component is also used elsewhere, keep it a plain (non-exported, non-endpoint) function and have the route view call it with `params.id`. The value `serverRouteComponent` returns is a component only so it fits the `component` field; mounting it any other way (through `lazy()`, or by hand) throws, since outside the match there are only merged params to call with.
+
+The router mounts the resolved component with the outlet as `children`, so a server component can be a layout, and it calls the same source under preload intent — link hover, `preloadRoute`, the [single-flight collector](#server-integration) — with the same derived args. What that call _means_ is the source's: the router does not choose the cache strategy or own the key.
+
+- `query(fn, key)`: link intent warms the entry the render reads, `revalidate("story")` and action responses refetch it, and the collector reproduces it so a mutation's response carries the route's fresh markup. Argument changes deliver into the mounted boundary — it morphs in place rather than remounting.
+- [`liveQuery(fn, key)`](#livequery-experimental): the frame stream stays open and the channel owns it — hover connects it (held through the preload window, so a hovered link is an open stream), `revalidate(key)` reconnects, and the mutation sweep and the single-flight collector both leave it alone — nothing pulls it server-side, and the stream is its own freshness.
+
+Anything else callable with the args works too; wrapping is what gives dedupe, preload, and revalidation.
+
+Mutations reach these routes the way they reach any query, and the cost model is worth knowing: a swept server route is a server-side re-render plus its markup in the response, not a small data blob. From a server action, `redirect(url)` re-collects everything the target shows and a bare `reload()` everything the current page shows — server routes included, shell and layouts too. On a server-component-heavy page, name what a mutation actually changed instead. `Router.keysFor(url)` answers the query keys of the server routes a URL shows, root to leaf — the app's own keys, from pure matching, so it works in an action and never spells a key:
+
+```ts
+export const addComment = action(async (form: FormData) => {
+  "use server";
+  await db.comments.add(form);
+  return reload({ revalidate: Router.keysFor(paths.stories(form.get("id"))) });
+});
+```
+
+Route keys, not addresses: every story page is refetched, which is what prefix matching gives a hand-written `revalidate("story")` too.
+
+An app shell is a pathless layout route whose `component` is a server component. With no pattern, its args are the constant `{ params: {}, search: undefined }` — one call, one address, persisting across every navigation — and as a route it gets preload, collection, and `revalidate` like any other. The `<Router>` root slot exists for client providers that need router context without following route rules; a server component has neither, so it does not go there:
+
+```tsx
+const routes = [{ component: serverRouteComponent(query(appShell, "shell")), children: pages }];
+render(() => <Router routes={routes} />, document.body);
+```
+
+`children` is the only client position the router fills, and the helper's type says so: a server component that requires other props — event handlers, refs, named slots — is rejected. Those come from the client, so that route has a client half; write it as an ordinary route component around `dynamic()`. Interaction that lives on the server — form posts to server actions via `action={addTodo}` — needs no client component at all.
+
 ### File-System Routes
 
 The `@solidjs/router/fs` adapter turns a `file-routes` manifest into route definitions — the app imports the virtual module, the adapter maps it:
@@ -387,22 +452,46 @@ export const route = defineFileRoute("/blog/:id", {
 
 export default function Post(props: RouteProps<typeof route>) {
   props.params.id; // string
-  props.data;      // ReturnType of the preload above
+  props.data; // ReturnType of the preload above
 }
 ```
 
 The pattern string is a typing witness — at runtime the manifest's path (from the filename) is the source of truth. With the plugin's `types` option generating a literal declaration for the virtual module, the file paths flow into `paths` and the typed hooks like a hand-written tree — `paths.blog(42)` typechecks, filters and search schemas included, and `useParams(paths.blog)` works as usual anywhere under the route.
 
+#### Server pages
+
+A route file's page can be a [server component](#server-component-routes-experimental): make the default export a `"use server"` function of the route args. With `fileRoutes({ serverComponents: true })` on the `file-routes` plugin, the scanner flags such a file and the adapter builds the route the hand-written tree spells out — `serverRouteComponent(query(fn, key))` with the file's path as the key. No `query`, key, or wrapper in the route file. (That option turns on server component _routes_; server components themselves are Solid's plugin's `serverFunctions: { components: true }`, the same switch a hand-written server route needs.)
+
+```tsx
+// routes/stories/[id].tsx
+import { defineFileRoute } from "@solidjs/router/fs";
+import type { ServerRouteArgs } from "@solidjs/router";
+
+export const route = defineFileRoute("/stories/:id", { search: storySearch });
+
+export default async function Story({ params, search }: ServerRouteArgs<typeof route>) {
+  "use server";
+  const story = await db.stories.get(params.id);
+  return props => <article>{story.title}{props.children}</article>;
+}
+```
+
+`ServerRouteArgs<typeof route>` reads the config as a witness like `RouteProps` does: `params` from the pattern, `search` as the schema's output (`undefined` with no schema). The key is the file — `Router.keysFor(paths.stories(7))` answers `["src/routes/stories/[id].tsx"]` (plus any server layouts above it), so an action names the page without spelling a path; because keys match by prefix, `revalidate("src/routes/stories")` refetches every page under the directory (pathless layouts have no route path of their own, so the file is what tells them apart). The directive has to be the first statement of the inline default export — behind a wrapper call or a re-export the scanner cannot see it, the page is code-split like a client page, and in development the adapter throws a directed error when the chunk resolves.
+
+A live page names its wrapper in the `route` config — `defineFileRoute("/feed", { query: liveQuery })` — and the adapter sources through that instead of `query`. The route file imports `liveQuery`, so only an app with a live page carries it.
+
+Apps with no server page pay nothing for any of this. The plugin folds the scan into `filesystem-routing/flags`, and the adapter's only path to `serverRouteComponent` and `query` is a module gated on that constant, so the branch — and with it the frames runtime — tree-shakes away. `pnpm build` asserts it.
+
 ## Typed Paths
 
 `paths` is a proxy inferred from the route tree. Property access descends into static segments, calls bind params, and it mirrors URL anatomy — params, then a search object, then a hash string:
 
 ```tsx
-paths.users(123)                          // ok — matchFilters flow into the callsite
-paths.users(2).settings                   // chainable into children
-paths.users(2, { tab: "x" }, "comments")  // "/users/2?tab=x#comments"
-paths.about()                             // zero-arg/search calls terminate to a plain string
-paths()                                   // "/" — the root
+paths.users(123); // ok — matchFilters flow into the callsite
+paths.users(2).settings; // chainable into children
+paths.users(2, { tab: "x" }, "comments"); // "/users/2?tab=x#comments"
+paths.about(); // zero-arg/search calls terminate to a plain string
+paths(); // "/" — the root
 ```
 
 Every node coerces via `toString`, so nodes drop straight into `href`, `navigate()`, and `redirect()` without explicit termination. Accessing a segment that doesn't exist in the tree, or binding a param with the wrong type, is a compile error.
@@ -413,14 +502,14 @@ There is no link component. Use `<a>`; the router intercepts same-origin clicks
 
 Behavior modifiers are attributes, so they work identically in client, server-rendered, and third-party markup:
 
-| attribute  | description                                                                    |
-| ---------- | ------------------------------------------------------------------------------ |
-| `replace`  | Replace the history entry instead of pushing                                   |
-| `noscroll` | Turn off scrolling to the top after navigation                                 |
+| attribute  | description                                                                                                     |
+| ---------- | --------------------------------------------------------------------------------------------------------------- |
+| `replace`  | Replace the history entry instead of pushing                                                                    |
+| `noscroll` | Turn off scrolling to the top after navigation                                                                  |
 | `state`    | JSON string [pushed](https://developer.mozilla.org/en-US/docs/Web/API/History/pushState) onto the history stack |
-| `preload`  | Set to `"false"` to opt this link out of hover/focus preloading                |
-| `link`     | Marks a router link when `explicitLinks` is enabled                            |
-| `target`   | Any value (e.g. `_self`) opts the anchor out of router handling                |
+| `preload`  | Set to `"false"` to opt this link out of hover/focus preloading                                                 |
+| `link`     | Marks a router link when `explicitLinks` is enabled                                                             |
+| `target`   | Any value (e.g. `_self`) opts the anchor out of router handling                                                 |
 
 ```tsx
 <a href={paths.login} replace>Log in</a>
@@ -431,9 +520,15 @@ Behavior modifiers are attributes, so they work identically in client, server-re
 Active and pending state is styled with CSS — one vocabulary for every kind of link:
 
 ```css
-nav a[aria-current="page"] { font-weight: 600; }        /* exact match */
-nav a[data-active]         { color: var(--accent); }    /* exact or prefix match */
-a[data-pending]            { opacity: 0.6; }            /* target of in-flight navigation */
+nav a[aria-current="page"] {
+  font-weight: 600;
+} /* exact match */
+nav a[data-active] {
+  color: var(--accent);
+} /* exact or prefix match */
+a[data-pending] {
+  opacity: 0.6;
+} /* target of in-flight navigation */
 ```
 
 (The root path only ever matches exactly, so `href={paths()}` doesn't light up on every page.)
@@ -471,10 +566,10 @@ const routes = defineRoutes([{ path: "/users/:id", component: User, preload: pre
 
 The preload function receives:
 
-| key      | type                                            | description                                                                                                                                                                                                                                     |
-| -------- | ----------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
-| params   | object                                          | The route parameters (same value as `useParams()` inside the route component)                                                                                                                                                                    |
-| location | `{ pathname, search, hash, query, state, key }` | Path information (corresponds to [`useLocation()`](#uselocation))                                                                                                                                                                                |
+| key      | type                                               | description                                                                                                                                                       |
+| -------- | -------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| params   | object                                             | The route parameters (same value as `useParams()` inside the route component)                                                                                     |
+| location | `{ pathname, search, hash, query, state, key }`    | Path information (corresponds to [`useLocation()`](#uselocation))                                                                                                 |
 | intent   | `"initial" \| "navigate" \| "native" \| "preload"` | Why this is being called: `initial` — first render; `navigate` — router navigation; `native` — browser back/forward; `preload` — link hover/focus, not navigating |
 
 The factory-level `preload` option is the app-wide counterpart: it runs once per mount/request with the merged params of every match, and its result reaches the root render-prop as `props.data`.
@@ -513,7 +608,7 @@ const todos = createProjection(() => getTodos(), []);
 Keys support targeted invalidation:
 
 ```ts
-getUser.key;       // "users"
+getUser.key; // "users"
 getUser.keyFor(5); // "users[5]"
 ```
 
@@ -549,13 +644,13 @@ Live queries ride the router's existing machinery rather than adding their own:
 - **Preload** — calling one in a preload function warms the connection, so navigation renders against an already-delivered value instead of holding the transition on connect.
 - **SSR** — the document face renders the first value; hydration adopts it and reconnects. Server-side, consumers of a key within one request observe the same value.
 - **Revalidation** — explicit `revalidate(key)` reconnects (the producer re-yields current state by contract). The post-mutation sweep leaves healthy connections alone: the stream is its own freshness mechanism.
-- **Single-flight** — a mutation's flight payload pushes straight into open channels, so mutated state lands in the same round trip.
+- **Single-flight** — live keys are neither collected nor swept: the stream is the freshness mechanism, and a mutation reaches a live query through its producer (the `watch` yielding the changed state), not through the mutation response. The flight-data seam that pushes payload values into open channels stays available to an integration that collects live keys itself.
 
 The callable carries the `query` conventions (`key`, `keyFor`) plus a reactive `status(...args)` read (`"idle" | "connecting" | "connected" | "reconnecting" | "closed"`) for surfacing connection state in UI.
 
 ### `action`
 
-A router action is *an action with a URL* — Solid's mutation primitive plus URL addressability, submission tracking, and response handling. Data helpers come from the router; response helpers (`redirect`, `reload`) come from `@solidjs/web` — they're protocol-level and work without the router:
+A router action is _an action with a URL_ — Solid's mutation primitive plus URL addressability, submission tracking, and response handling. Data helpers come from the router; response helpers (`redirect`, `reload`) come from `@solidjs/web` — they're protocol-level and work without the router:
 
 ```tsx
 import { action } from "@solidjs/router";
@@ -580,7 +675,10 @@ const updateUser = action(async (form: FormData) => {
 Actions only work with POST requests, so put `method="post"` on your form. Submitting forms get `aria-busy="true"` automatically while the action (including its revalidation) is in flight — the same CSS story as links:
 
 ```css
-form[aria-busy] button { pointer-events: none; opacity: 0.6; }
+form[aria-busy] button {
+  pointer-events: none;
+  opacity: 0.6;
+}
 ```
 
 Forms work without JavaScript: a real POST, a redirect back, and the result seeded into submission state through a one-shot flash cookie. Single-flight mutations are on by default — the mutation response carries the refreshed route data in the same round trip.
@@ -664,7 +762,7 @@ const routes = defineRoutes([
 
 ```tsx
 const [search, setSearch] = useSearchParams(paths.search);
-search.page;                          // number (parsed, not "2")
+search.page; // number (parsed, not "2")
 setSearch({ page: search.page + 1 }); // typed setter
 
 <a href={paths.search({ q: "solid", page: 2 })}>Search</a>; // typed builder
@@ -678,26 +776,26 @@ Without a schema, `useSearchParams()` behaves as before: raw string values, merg
 createRouter(config);
 ```
 
-| option          | type                       | description                                                                                            |
-| --------------- | -------------------------- | ------------------------------------------------------------------------------------------------------ |
-| `routes`        | `RouteDefinition[]`        | The route tree — inline arrays infer literally; wrap extracted trees in `defineRoutes`                   |
-| `base`          | `string`                   | Base url to use for matching routes                                                                     |
-| `preload`       | `RoutePreloadFunc`         | App-wide preload: once per mount/request, result reaches the root render-prop as `props.data`           |
-| `history`       | `RouterHistory`            | History adapter; defaults to browser history on the client and the request URL on the server            |
-| `singleFlight`  | `boolean`                  | Single-flight mutations, default `true`                                                                 |
-| `actionBase`    | `string`                   | Root url for server actions, default `/_server`                                                         |
-| `preloadLinks`  | `boolean`                  | Preload route code/data on link hover and focus, default `true`                                         |
-| `explicitLinks` | `boolean`                  | Require the `link` attribute for router handling instead of intercepting all anchors, default `false`   |
-| `transformUrl`  | `(url: string) => string`  | Rewrite URLs before matching                                                                            |
+| option          | type                      | description                                                                                           |
+| --------------- | ------------------------- | ----------------------------------------------------------------------------------------------------- |
+| `routes`        | `RouteDefinition[]`       | The route tree — inline arrays infer literally; wrap extracted trees in `defineRoutes`                |
+| `base`          | `string`                  | Base url to use for matching routes                                                                   |
+| `preload`       | `RoutePreloadFunc`        | App-wide preload: once per mount/request, result reaches the root render-prop as `props.data`         |
+| `history`       | `RouterHistory`           | History adapter; defaults to browser history on the client and the request URL on the server          |
+| `singleFlight`  | `boolean`                 | Single-flight mutations, default `true`                                                               |
+| `actionBase`    | `string`                  | Root url for server actions, default `/_server`                                                       |
+| `preloadLinks`  | `boolean`                 | Preload route code/data on link hover and focus, default `true`                                       |
+| `explicitLinks` | `boolean`                 | Require the `link` attribute for router handling instead of intercepting all anchors, default `false` |
+| `transformUrl`  | `(url: string) => string` | Rewrite URLs before matching                                                                          |
 
 The returned instance is the provider component and carries the static surface:
 
-| member    | description                                                                                     |
-| --------- | ------------------------------------------------------------------------------------------------ |
-| `paths`   | The [typed path proxy](#typed-paths)                                                             |
-| `match`   | Pure matching against an arbitrary URL — no rendering or request context; root→leaf, `[]` if none |
-| `routes`  | The config tree                                                                                   |
-| `config`  | The full config — lets server integrations consume the instance directly                          |
+| member   | description                                                                                       |
+| -------- | ------------------------------------------------------------------------------------------------- |
+| `paths`  | The [typed path proxy](#typed-paths)                                                              |
+| `match`  | Pure matching against an arbitrary URL — no rendering or request context; root→leaf, `[]` if none |
+| `routes` | The config tree                                                                                   |
+| `config` | The full config — lets server integrations consume the instance directly                          |
 
 ## Router Primitives
 
@@ -708,7 +806,7 @@ Hooks read the live session off router context.
 Retrieves a reactive, store-like object of the current route's path parameters. Pass a paths node for typing:
 
 ```tsx
-const params = useParams();            // Params (strings)
+const params = useParams(); // Params (strings)
 const params = useParams(paths.users); // { id: string } — typed from the tree
 ```
 
@@ -756,7 +854,7 @@ In Solid's dev and observe builds the router also declares every navigation to t
 
 ### useMatch
 
-Tests a path *pattern you supply* against the current location; returns a memo of match information or `undefined`. It never consults the route tree — the pattern doesn't have to correspond to a defined route. The match's `params` are typed from the pattern, and a typed path node works too (a concrete URL — useful for "am I here" checks):
+Tests a path _pattern you supply_ against the current location; returns a memo of match information or `undefined`. It never consults the route tree — the pattern doesn't have to correspond to a defined route. The match's `params` are typed from the pattern, and a typed path node works too (a concrete URL — useful for "am I here" checks):
 
 ```tsx
 const match = useMatch(() => "/admin/*rest");
@@ -768,7 +866,7 @@ const here = useMatch(() => paths.users(2));
 
 ### useRouteMatches
 
-Returns an accessor of the router's *resolved* matches for the current location — the chain of route definitions producing the current render, outermost first. This is the counterpart to `useMatch`: one reflects the route tree, the other tests a pattern. Useful for reading `info` metadata:
+Returns an accessor of the router's _resolved_ matches for the current location — the chain of route definitions producing the current render, outermost first. This is the counterpart to `useMatch`: one reflects the route tree, the other tests a pattern. Useful for reading `info` metadata:
 
 ```tsx
 const matches = useRouteMatches();
@@ -890,7 +988,7 @@ This guide maps from the stable 0.x releases (Solid 1). 1.0 removes the componen
 <Router root={App}>
   <Route path="/users" component={Users} />
   <Route path="/users/:id" component={User} />
-</Router>
+</Router>;
 
 // 1.0
 const Router = createRouter({
@@ -900,7 +998,7 @@ const Router = createRouter({
   ]
 });
 
-<Router>{props => <App {...props} />}</Router>
+<Router>{props => <App {...props} />}</Router>;
 ```
 
 - `<HashRouter>` → `createRouter({ routes, history: hashHistory() })`

package/dist/data/liveQuery.d.ts

@@ -18,11 +18,11 @@ export type LiveFunction<T extends (...args: any) => any> = T extends (...args:
  *   definite rejection (4xx: the transport stamps HTTP statuses onto
  *   failures) ends the channel and surfaces the error to consumers, as does
  *   a first-connect failure.
- * - Server functions are declared GET at creation (like `query`). Live
- *   queries participate in single-flight on the delivery side: a mutation's
- *   flight payload pushes straight into open channels (the mutation
- *   response is the round trip), while the post-mutation sweep leaves the
- *   healthy connection in place — the live stream stays authoritative.
+ * - Server functions are declared GET at creation (like `query`). Live keys
+ *   are neither collected for single-flight nor swept after a mutation: the
+ *   stream is the freshness mechanism, and the mutation reaches a live
+ *   query through its producer. (The flight-data hook below still adopts a
+ *   live key an integration collects itself.)
  * - Calling under preload intent warms the channel (a temporary hold keeps
  *   it open through the preload window), so navigation renders against an
  *   already-connected stream instead of holding the transition on connect

package/dist/data/liveQuery.js

@@ -205,7 +205,7 @@ function subscriberIterable(open) {
                 }
             };
             return {
-                next: () => (released ? Promise.resolve({ done: true, value: undefined }) : pull()),
+                next: () => released ? Promise.resolve({ done: true, value: undefined }) : pull(),
                 return(value) {
                     release();
                     return Promise.resolve({ done: true, value });
@@ -236,10 +236,12 @@ function push(ch, value) {
 //   connection is alive and is itself the freshness mechanism — a
 //   push-driven producer yields the mutated state on its own, and tearing
 //   down healthy connections on every mutation defeats the model.
-// - Single-flight payloads deliver INTO open channels, exactly as they seed
-//   the query cache: the mutation response is the round trip, the channel
-//   adopts the value immediately, and the live stream stays authoritative
-//   for everything after.
+// - A single-flight payload carrying a live key delivers INTO the open
+//   channel rather than reconnecting it. The router's own collector does not
+//   produce live keys (the stream is the freshness mechanism; collection
+//   for live server components is an open question — a mutation's region
+//   would outrank the standing frame stream under the transport's version
+//   policy), so this path serves an integration that collects them itself.
 let hooked = false;
 function hookRevalidate() {
     if (hooked)
@@ -293,11 +295,11 @@ function hookRevalidate() {
  *   definite rejection (4xx: the transport stamps HTTP statuses onto
  *   failures) ends the channel and surfaces the error to consumers, as does
  *   a first-connect failure.
- * - Server functions are declared GET at creation (like `query`). Live
- *   queries participate in single-flight on the delivery side: a mutation's
- *   flight payload pushes straight into open channels (the mutation
- *   response is the round trip), while the post-mutation sweep leaves the
- *   healthy connection in place — the live stream stays authoritative.
+ * - Server functions are declared GET at creation (like `query`). Live keys
+ *   are neither collected for single-flight nor swept after a mutation: the
+ *   stream is the freshness mechanism, and the mutation reaches a live
+ *   query through its producer. (The flight-data hook below still adopts a
+ *   live key an integration collects itself.)
  * - Calling under preload intent warms the channel (a temporary hold keeps
  *   it open through the preload window), so navigation renders against an
  *   already-connected stream instead of holding the transition on connect
@@ -349,7 +351,7 @@ export function liveQuery(fn, name) {
             // reads the same guarantee). Channels live in the event, retained
             // past teardown so a later consumer replays the settled value instead
             // of reinvoking; the producer still closes with its last consumer.
-            const router = (e.router || (e.router = {}));
+            const router = e.router || (e.router = {});
             const channels = router.liveChannels || (router.liveChannels = new Map());
             return subscriberIterable(() => openChannel(channels, key, () => fn(...args), false, true));
         }

package/dist/fs.d.ts

@@ -1,3 +1,4 @@
+import type { ServerPageQuery } from "./fsServer.js";
 import type { DefinedRouteFilters, RouteParams, RoutePreloadFunc, RoutePreloadFuncArgs, RouteInfo, RouteSectionComponent, StandardSchemaV1, TypedRouteConfig, ValidFilters } from "./types.js";
 /**
  * The type `defineFileRoute` hands back: `matchFilters` and `search` stay
@@ -14,6 +15,7 @@ export type FileRouteConfig<S extends string = string, T = unknown, F = undefine
 }) & {
     preload?: RoutePreloadFunc<T> | undefined;
     info?: RouteInfo | undefined;
+    query?: ServerPageQuery | undefined;
 };
 /**
  * Identity helper for a route file's `route` export that types `preload`'s
@@ -39,6 +41,8 @@ export declare function defineFileRoute<S extends string, T = unknown, const F =
     /** Standard Schema validator for this route's search params; its input type flows into the typed path proxy. */
     search?: Sch;
     info?: RouteInfo | undefined;
+    /** For a server page: the wrapper its source goes through — `query` unless named, e.g. `liveQuery`. */
+    query?: ServerPageQuery | undefined;
 }): FileRouteConfig<S, T, F, Sch>;
 /** A code-split module ref: delivered as a dynamic import. */
 export interface FileRouteLazyRef<M = Record<string, unknown>> {
@@ -54,7 +58,9 @@ export interface FileRouteEagerRef<M = Record<string, unknown>> {
 export interface FileRouteEntry {
     path: string;
     page?: boolean;
-    /** Code-split by default; an eager ref when delivered with `codeSplitting: false`. */
+    /** The page component is a `"use server"` function; its `$component` is an eager ref to the stub. */
+    server?: boolean;
+    /** Code-split by default; an eager ref when delivered with `codeSplitting: false` or for a server page. */
     $component?: FileRouteLazyRef<any> | FileRouteEagerRef<any> | undefined;
     $$route?: FileRouteEagerRef<any> | undefined;
     children?: readonly FileRouteEntry[] | undefined;

package/dist/fs.js

@@ -1,4 +1,7 @@
-import { lazy } from "solid-js";
+import { DEV, lazy } from "solid-js";
+import { isServerFunction } from "@solidjs/web";
+import { serverRoutes } from "filesystem-routing/flags";
+import * as server from "./fsServer.js";
 /**
  * Identity helper for a route file's `route` export that types `preload`'s
  * `args.params` from a pattern witness — the file's path pattern, which the
@@ -31,15 +34,36 @@ export function defineFileRoute(path, config) {
  */
 export function fileRoutes(entries) {
     const components = new Map();
-    const componentOf = (ref) => {
+    const componentOf = (entry, config) => {
+        const ref = entry.$component;
         if ("require" in ref) {
-            return ref.require().default;
+            const component = ref.require()
+                .default;
+            // A server page: the stub is the source; the file is the key (unique,
+            // and a directory prefix is a subtree for `revalidate`).
+            return serverRoutes && entry.server
+                ? server.serverRoute(component, (ref.src || entry.path).split("?")[0], config)
+                : component;
         }
         let component = components.get(ref.src);
         if (!component) {
             // moduleUrl is lazy()'s third argument as of solid 2.0.0-rc.1 (options
             // moved second); route components are default exports, so no { export }.
-            component = lazy(ref.import, undefined, ref.src);
+            component = lazy(
+            // A `"use server"` default the scanner did not see (behind a wrapper
+            // call or a re-export) — or scanned without the plugin's
+            // `serverComponents` option — was code-split like a client page:
+            // say so in development rather than mount a stub as a component.
+            DEV
+                ? () => ref.import().then(mod => {
+                    if (isServerFunction(mod.default))
+                        throw new Error(`Route module "${ref.src}" exports a server function as its page, but it ` +
+                            "was delivered as a client page. Enable `serverComponents: true` on the " +
+                            'file-routes plugin and make the `"use server"` directive the first ' +
+                            "statement of the inline default export.");
+                    return mod;
+                })
+                : ref.import, undefined, ref.src);
             components.set(ref.src, component);
         }
         return component;
@@ -49,7 +73,7 @@ export function fileRoutes(entries) {
         return {
             ...config,
             path: entry.path,
-            component: entry.$component ? componentOf(entry.$component) : undefined,
+            component: entry.$component ? componentOf(entry, config) : undefined,
             info: { ...config.info, filesystem: true },
             children: entry.children ? entry.children.map(toRoute) : undefined
         };

package/dist/fsServer.d.ts

@@ -0,0 +1,15 @@
+import type { RouteSectionComponent } from "./types.js";
+/**
+ * The wrapper a server page's source goes through: `query` unless the route
+ * config names another — `liveQuery`, imported by the route file that wants
+ * it, so only that app carries it.
+ */
+export type ServerPageQuery = (fn: (...args: any[]) => any, key: string) => (...args: any[]) => any;
+/**
+ * The server page half of the fs adapter — the only importer of `query` and
+ * `serverRouteComponent`. fs.ts reaches it behind `serverRoutes` from
+ * `filesystem-routing/flags`, so an app with no server page never bundles it.
+ */
+export declare function serverRoute(fn: (...args: any[]) => any, key: string, config?: {
+    query?: ServerPageQuery | undefined;
+}): RouteSectionComponent;

package/dist/fsServer.js

@@ -0,0 +1,10 @@
+import { query } from "./data/query.js";
+import { serverRouteComponent } from "./serverRouteComponent.js";
+/**
+ * The server page half of the fs adapter — the only importer of `query` and
+ * `serverRouteComponent`. fs.ts reaches it behind `serverRoutes` from
+ * `filesystem-routing/flags`, so an app with no server page never bundles it.
+ */
+export function serverRoute(fn, key, config) {
+    return serverRouteComponent((config?.query ?? query)(fn, key));
+}