@abide/abide 0.117.2 → 0.118.0

package/src/server/answerRequest.ts

@@ -100,6 +100,8 @@ type ServerRoute = {
     // 38.28 — the modules a browser loads at this address, the page's then its layouts', as keys
     // into the manifest `manifestOf` reads.
     clientModules: string[]
+    // 23.26 — each matcher its pattern names, to the anchored source the build resolved it to.
+    matchers: Record<string, string>
 }
 
 // 35.2 — an error page, and the directory it answers for.
@@ -122,6 +124,7 @@ type Ranked = RankedError & {
  */
 type RouteRow = {
     pattern: string
+    matchers: Record<string, string>
     segments: Segment[]
     page: Ranked | undefined
     handlers: Map<Method, Mounted>
@@ -178,6 +181,16 @@ export type AppSources = {
 // 41.29 — the seed sink of a render no page hydrates: every call is left to run when it is made.
 const SEEDS_NOTHING: PageRender['seed'] = () => false
 
+// 35.19 — what fetch calls a navigation request's destinations, and a script's `fetch`.
+const PAGE_DESTINATIONS = new Set([
+    'document',
+    'embed',
+    'frame',
+    'iframe',
+    'object',
+    'empty',
+])
+
 /** The `Response` to one request: a handler, a surface of abide's own, a file, or a page. */
 export async function answerRequest(
     app: AppSources,
@@ -331,6 +344,17 @@ async function answerMatched(
             headers: { 'cache-control': 'no-store' },
         })
 
+    // 35.19 — A REQUEST THAT CANNOT DISPLAY A PAGE, such as the `/favicon.ico` a browser asks every
+    // site for where a `[param]` page matches it: refused before setup, so no handler runs for it
+    // and no caller is minted. Bare, because an error page would set up too and nothing shows it;
+    // `no-store`, because the address answers a navigation with the page.
+    const destination = request.headers.get('sec-fetch-dest')
+    if (destination !== null && !PAGE_DESTINATIONS.has(destination))
+        return new Response(null, {
+            status: 404,
+            headers: { 'cache-control': 'no-store' },
+        })
+
     // 33.4 — a prop is an ACCESSOR, which is the contract `renderComponent` renders a child under
     // and the one the client router mounts a page under; the params are the record `firstMatch`
     // hands the client for this same address.
@@ -534,16 +558,22 @@ export async function appSources(parts: SourceParts): Promise<AppSources> {
             pattern: route.pattern,
             load: route.load,
             layouts: route.layouts,
+            matchers: route.matchers,
             document: documentOf(route.clientModules),
         })
     // 19.1 — the build refused two files at one route and method, so a route is one row however
-    // many methods answer at it.
+    // many methods answer at it — and 23.27 one matcher per position, so whichever file opens the
+    // row brings what every file at it would.
     const rows = new Map<string, Omit<RouteRow, 'segments'>>()
-    const rowAt = (pattern: string): Omit<RouteRow, 'segments'> => {
+    const rowAt = (
+        pattern: string,
+        matchers: Record<string, string>,
+    ): Omit<RouteRow, 'segments'> => {
         let row = rows.get(pattern)
         if (row === undefined) {
             row = {
                 pattern,
+                matchers,
                 page: undefined,
                 handlers: new Map(),
                 answers: new Map(),
@@ -552,12 +582,19 @@ export async function appSources(parts: SourceParts): Promise<AppSources> {
         }
         return row
     }
-    for (const page of rankRoutes(pages)) rowAt(page.pattern).page = page
+    for (const page of rankRoutes(pages))
+        rowAt(page.pattern, page.matchers).page = page
     for (const handler of mounted.handlers.values())
-        rowAt(handler.address).handlers.set(handler.method, handler)
+        rowAt(handler.address, handler.matchers).handlers.set(
+            handler.method,
+            handler,
+        )
     const errors: RankedError[] = []
     for (const error of parts.table.errors)
-        errors.push({ ...error, segments: parseRoutePattern(error.pattern) })
+        errors.push({
+            ...error,
+            segments: parseRoutePattern(error.pattern, error.matchers),
+        })
     errors.sort((a, b) => b.segments.length - a.segments.length)
     const sources: AppSources = {
         routes: rankRoutes([...rows.values()]),

package/src/server/answerRpc.ts

@@ -72,6 +72,8 @@ export type Mount = {
     export: string
     /** The route its hooks are filed at, which its rungs are read over (37.1, 16.72). */
     scope: string
+    /** 23.26 — each matcher its address names, to the anchored source its row is ranked with. */
+    matchers: Record<string, string>
     /** Whether it is a private handler, listed nowhere (16.71). */
     private: boolean
     /** Whether a browser is handed a wrapper for it. 20.4. */
@@ -154,6 +156,7 @@ export function mountedOwn(
             name,
             export: name,
             scope: '/',
+            matchers: {},
             private: false,
             ui: false,
             cli: false,

package/src/server/appTree.ts

@@ -1,6 +1,6 @@
 // 23.14 — WHERE AN APP'S ADDRESSES ARE, read off the tree in one walk. A file directly in a directory
 // below the root is an address — a page, a layout, an error page or a handler file — and nothing
-// else is there but its tests (23.22); a fence is never one (23.15): `public` holds files answered as
+// else is there but its tests and the param files its segments name (23.22, 23.24); a fence is never one (23.15): `public` holds files answered as
 // authored at the path of the directories above it, and `lib` holds the rest, a server file among it
 // (23.23). So listing a directory lists its routes.
 //
@@ -22,6 +22,8 @@ import {
 import {
     DIRECTORY_FILES,
     isDeclarationFile,
+    isHandlerFile,
+    isParamFile,
     isServerFile,
     isBenchFile,
     isTestFile,
@@ -36,6 +38,8 @@ type AppFiles = {
     abide: string[]
     /** Every handler file, in path order. */
     handlers: string[]
+    /** 23.24 — every param file directly in an address directory, in path order. */
+    params: string[]
     /** Every module under a `lib` directory, in path order — read for 37.13. */
     modules: string[]
     /** Every file under a `public` directory, to the address it is answered at below the mount. */
@@ -52,6 +56,7 @@ export function appFiles(root: string, refusals: Refusals): AppFiles {
     const files: AppFiles = {
         abide: [],
         handlers: [],
+        params: [],
         modules: [],
         published: new Map(),
     }
@@ -61,6 +66,7 @@ export function appFiles(root: string, refusals: Refusals): AppFiles {
     walk(root, '', undefined, files, refusals, packaged)
     files.abide.sort()
     files.handlers.sort()
+    files.params.sort()
     files.modules.sort()
     return files
 }
@@ -126,13 +132,17 @@ function walk(
                 isDeclarationFile(path)
             )
                 continue
-            if (!abide && !isModule(path)) {
+            if (isParamFile(path)) {
+                files.params.push(path)
+                continue
+            }
+            if (!abide && !isHandlerFile(path)) {
                 if (packaged && relative === '' && !path.endsWith('.ts'))
                     continue
                 refusals.at(
                     path,
                     new Error(
-                        `abide: ${path} is directly in an address directory, which holds pages, layouts, error pages, handler files, test files, bench files and declaration files alone. Move it into a lib directory, beside it or in any directory above it. RULEBOOK 23.22.`,
+                        `abide: ${path} is directly in an address directory, which holds pages, layouts, error pages, handler files, param files, test files, bench files and declaration files alone. ${path.endsWith('.ts') ? 'Name a handler file <name>.handler.ts, or move anything else' : 'Move it'} into a lib directory, beside it or in any directory above it. RULEBOOK 23.22.`,
                     ),
                 )
                 continue
@@ -211,8 +221,7 @@ export function holdsApp(root: string): boolean {
     return !appSourcesUnder(root, '').next().done
 }
 
-// Every `.abide` under `directory`, and every handler file — a module whose place is an address, and
-// no server file (23.23).
+// Every `.abide` under `directory`, and every handler file whose place is an address.
 function* appSourcesUnder(
     directory: string,
     relative: string,
@@ -230,9 +239,7 @@ function* appSourcesUnder(
             yield* appSourcesUnder(`${directory}/${entry.name}`, `${path}/`)
         else if (
             path.endsWith('.abide') ||
-            (isModule(path) &&
-                !isServerFile(path) &&
-                placeOf(path) === 'address')
+            (isHandlerFile(path) && placeOf(path) === 'address')
         )
             yield path
     }

package/src/server/generatedSurfaces.ts

@@ -18,7 +18,7 @@ import { essenceOf } from '#shared/framing.ts'
 import { namedLogger } from '#shared/log.ts'
 import { mounted } from '#shared/mount.ts'
 import { type Reactive, reactive } from '#shared/reactive/index.ts'
-import { parseRoutePattern } from '#shared/routePattern.ts'
+import { parseRoutePattern, type Segment } from '#shared/routePattern.ts'
 import { argsInURL, rpcRequest } from '#shared/rpcRequest.ts'
 import { answered } from './answerFailure.ts'
 import { bodyWithin, type Mounted } from './answerRpc.ts'
@@ -134,13 +134,19 @@ function openApiOf(handlers: Map<string, Mounted>): {
         for (const segment of parseRoutePattern(each.address)) {
             if (segment.kind === 'static') continue
             inPath.add(segment.name)
+            const declared = schema?.properties?.[segment.name] ?? {
+                type: 'string',
+            }
+            // 20.23 — and what the segment takes, save a rest's: its value is the parts joined,
+            // which one part's pattern does not describe.
             const parameter: Record<string, unknown> = {
                 name: segment.name,
                 in: 'path',
                 required: true,
-                schema: schema?.properties?.[segment.name] ?? {
-                    type: 'string',
-                },
+                schema:
+                    segment.kind === 'rest'
+                        ? declared
+                        : patterned(declared, patternOf(segment, each.matchers)),
             }
             if (segment.kind === 'optional')
                 parameter.description = 'May be left out, with its segment.'
@@ -172,8 +178,11 @@ function openApiOf(handlers: Map<string, Mounted>): {
                     },
                 },
             }
-        // OpenAPI spells a parameter `{id}` where a route spells it `[id]`.
-        const path = each.address.replace(/\[+(?:\.\.\.)?([^\]]+)\]+/g, '{$1}')
+        // OpenAPI spells a parameter `{id}` where a route spells it `[id]`, and names no matcher.
+        const path = each.address.replace(
+            /\[+(?:\.\.\.)?([^\]=]+)(?:=[^\]]*)?\]+/g,
+            '{$1}',
+        )
         paths[path] ??= {}
         ;(paths[path] as Record<string, unknown>)[each.method.toLowerCase()] =
             operation
@@ -291,7 +300,9 @@ export class McpSurface {
             listing.push({
                 name: tool.name,
                 description: tool.description ?? '',
-                inputSchema: toolInput(tool.schema),
+                inputSchema: toolInput(
+                    withPathPatterns(tool.schema, tool.address, tool.matchers),
+                ),
                 // 20.14 — what the method promises: a `GET` is safe, and a `GET`, a `PUT` and a
                 // `DELETE` idempotent. Any other write may destroy, and nothing says it does not.
                 annotations: {
@@ -454,6 +465,63 @@ function logCall(
     )
 }
 
+/** 20.23 — the anchored pattern a segment takes a part by: its matcher's, or 30.34's default. */
+function patternOf(segment: Segment, matchers: Record<string, string>): string {
+    return segment.matcher === undefined
+        ? PERIODLESS_PATTERN
+        : (matchers[segment.matcher] ?? PERIODLESS_PATTERN)
+}
+
+const PERIODLESS_PATTERN = '^[^.]+$'
+
+/** `declared` constrained to `pattern` too: beside a pattern it declares itself, not over it. */
+function patterned(declared: unknown, pattern: string): unknown {
+    if (declared === null || typeof declared !== 'object') return { pattern }
+    return 'pattern' in declared
+        ? { allOf: [declared, { pattern }] }
+        : { ...declared, pattern }
+}
+
+/**
+ * 20.23 — `schema` with each route parameter it declares constrained to what its segment takes, a
+ * rest's on each of its items; `schema` itself where the route has no parameter it declares.
+ */
+function withPathPatterns(
+    schema: unknown,
+    address: string,
+    matchers: Record<string, string>,
+): unknown {
+    if (schema === null || typeof schema !== 'object') return schema
+    const properties = (schema as { properties?: Record<string, unknown> })
+        .properties
+    if (properties === undefined) return schema
+    const constrained: Record<string, unknown> = { ...properties }
+    let changed = false
+    for (const segment of parseRoutePattern(address)) {
+        if (segment.kind === 'static') continue
+        const declared = properties[segment.name]
+        if (declared === undefined) continue
+        const pattern = patternOf(segment, matchers)
+        constrained[segment.name] =
+            segment.kind === 'rest' &&
+            declared !== null &&
+            typeof declared === 'object' &&
+            'items' in declared
+                ? {
+                      ...declared,
+                      items: patterned(
+                          (declared as { items: unknown }).items,
+                          pattern,
+                      ),
+                  }
+                : segment.kind === 'rest'
+                  ? declared
+                  : patterned(declared, pattern)
+        changed = true
+    }
+    return changed ? { ...schema, properties: constrained } : schema
+}
+
 /**
  * `schema` as a tool's `inputSchema`, its top-level `type` `object` whatever it declared there, or
  * `undefined` where no value it admits is an object. 20.19, 20.20.

package/src/server/placement.ts

@@ -104,6 +104,16 @@ export function isServerFile(path: string): boolean {
 
 const SERVER_FILE = /[^/]\.server\.[^./]+$/
 
+/** 16.2 — whether `path` names a handler file, `<name>.handler.ts`, whose default export answers at its route. */
+export function isHandlerFile(path: string): boolean {
+    return path.endsWith('.handler.ts')
+}
+
+/** 23.24 — whether `path` names a param file, `<NAME>.param.ts`, declaring the matcher `NAME`. */
+export function isParamFile(path: string): boolean {
+    return path.endsWith('.param.ts')
+}
+
 /** Whether `path` names a test file, which is never an address nor a module the app runs. */
 export function isTestFile(path: string): boolean {
     return path.endsWith('.test.ts')
@@ -127,7 +137,7 @@ export function skipped(name: string): boolean {
 /**
  * The route a file answers at — its path below the root without its extension.
  *
- * 23.14 — `media/[id].abide` and `media/getGrid.ts` are `/media/[id]` and `/media/getGrid`; an
+ * 23.14 — `media/[id].abide` and `media/getGrid.handler.ts` are `/media/[id]` and `/media/getGrid`; an
  * `index.abide`, a `layout.abide` and an `error.abide` are their directory's.
  */
 export function routeOf(path: string): string {
@@ -138,7 +148,7 @@ export function routeOf(path: string): string {
     return `/${parts.filter((part) => part !== '').join('/')}`
 }
 
-const EXTENSION = /\.(?:abide|ts)$/
+const EXTENSION = /\.(?:abide|handler\.ts)$/
 
 /** 23.14, 23.18 — the names whose route is their directory's, and so a route's wherever they stand. */
 export const DIRECTORY_FILES = new Set([

package/src/server/remote.ts

@@ -115,11 +115,15 @@ function handlerAt(
     address: string,
     method: string | undefined,
 ): Mount | undefined {
-    const rows: { pattern: string; mount: Mount }[] = []
+    const rows: {
+        pattern: string
+        matchers: Record<string, string>
+        mount: Mount
+    }[] = []
     for (const mount of handlers) {
         if (method !== undefined && mount.method !== method) continue
         if (mount.address === address) return mount
-        rows.push({ pattern: mount.address, mount })
+        rows.push({ pattern: mount.address, matchers: mount.matchers, mount })
     }
     return firstMatch(rankRoutes(rows), partsOf(address) ?? [])?.route.mount
 }

package/src/server/surfaceOf.ts

@@ -17,6 +17,8 @@ export type Listed = {
     schema: unknown
     /** What it answers, as JSON Schema, where its type says. 19.21. */
     result: unknown
+    /** 23.26 — each matcher its address names, to its anchored source. */
+    matchers: Record<string, string>
 }
 
 /**
@@ -50,6 +52,7 @@ export function surfaceOf(
             live === undefined ? mount.description : live.handler.description,
         schema: live === undefined ? mount.args : live.argsDocument,
         result: mount.result,
+        matchers: mount.matchers,
     }
 }
 
@@ -60,7 +63,8 @@ export function surfaceOf(
  * and dots dropped, so `/media/[id]` reads `media_id` rather than `media__id_`.
  */
 export function surfaceName(method: Method, route: string): string {
-    return `${method.toLowerCase()}${route === '/' ? '' : route.replace(/[[\].]/g, '')}`.replace(
+    // 19.1 — a matcher is no part of what a route is, so none of its name: `=NAME` goes first.
+    return `${method.toLowerCase()}${route === '/' ? '' : route.replace(/=[^\]]*/g, '').replace(/[[\].]/g, '')}`.replace(
         /[^a-zA-Z0-9-]/g,
         '_',
     )

package/src/shared/filledPath.ts

@@ -42,32 +42,38 @@ export function filledSegments(
         }
         if (segment.kind === 'rest' && Array.isArray(value)) {
             for (const each of value)
-                address += `/${encodedSegment(spelled, segment.name, each, refused)}`
+                address += `/${encodedSegment(spelled, segment, each, refused)}`
             continue
         }
-        address += `/${encodedSegment(spelled, segment.name, value, refused)}`
+        address += `/${encodedSegment(spelled, segment, value, refused)}`
     }
     return address === '' ? '/' : address
 }
 
 /**
- * A param value encoded as one path segment; `.` and `..` are refused.
+ * A param value encoded as one path segment, refused where no address can carry it.
  *
- * 30.19 — A VALUE OF `.` OR `..` HAS NO SPELLING AS A SEGMENT: the URL parser collapses it as a
- * dot-segment, and `%2E` / `%2E%2E` with it, so the address would land on another route. Refused
- * rather than written, as a missing required segment is (30.3).
+ * 30.19 — A VALUE NO SEGMENT TAKES HAS NO SPELLING: one carrying a period, where the segment names no
+ * matcher to lift the default (30.34), and `.` or `..` whatever it names (30.36), which the URL
+ * parser collapses as a dot-segment, `%2E` / `%2E%2E` with it. Refused rather than written, as a
+ * missing required segment is (30.3). A named matcher is not run here: the literal says a matcher
+ * is named, and only a route table holds the regex (23.26).
  */
 function encodedSegment(
     spelled: string,
-    name: string,
+    segment: Segment,
     value: unknown,
     refused: (name: string, message: string) => unknown,
 ): string {
     const text = String(value)
-    if (text === '.' || text === '..')
+    const carried =
+        segment.matcher === undefined
+            ? !text.includes('.')
+            : text !== '.' && text !== '..'
+    if (!carried)
         throw refused(
-            name,
-            `abide: ${spelled} was given '${text}' for '${name}', and no address carries it as a segment — the URL parser resolves it to another route. RULEBOOK 30.19.`,
+            segment.name,
+            `abide: ${spelled} was given '${text}' for '${segment.name}', and no address carries ${segment.matcher === undefined ? 'a period in a param naming no matcher' : 'a dot-segment'}. RULEBOOK 30.19.`,
         )
     return encodeURIComponent(text)
 }

package/src/shared/matchRoute.ts

@@ -56,9 +56,16 @@ function walk(
         return prefix || at === parts.length ? {} : null
     const segment = segments[index] as Segment
     // 30.5 — A REST TAKES THE MOST THE SEGMENTS AFTER IT LEAVE, nothing included, so a handler's
-    // name after one (`/docs/[...path]/save`) is reached rather than spent on the rest.
+    // name after one (`/docs/[...path]/save`) is reached rather than spent on the rest — and 30.35,
+    // never past a part it does not accept.
     if (segment.kind === 'rest') {
-        for (let end = parts.length; end >= at; end -= 1) {
+        let furthest = at
+        while (
+            furthest < parts.length &&
+            segment.accepts.test(parts[furthest] as string)
+        )
+            furthest += 1
+        for (let end = furthest; end >= at; end -= 1) {
             const params = walk(segments, index + 1, parts, end, prefix)
             if (params !== null) {
                 params[segment.name] = parts.slice(at, end)
@@ -68,8 +75,12 @@ function walk(
         return null
     }
     const part = parts[at]
+    // 30.34, 30.35 — A PARAM TAKES A PART ITS SEGMENT ACCEPTS: the matcher it names, or, naming
+    // none, no part carrying a period, which is how a file is named — the `/favicon.ico` a browser
+    // asks every site for is no `[param]` page's to answer.
+    const takeable = part !== undefined && segment.accepts.test(part)
     if (segment.kind === 'optional') {
-        if (part !== undefined) {
+        if (takeable) {
             const taken = walk(segments, index + 1, parts, at + 1, prefix)
             if (taken !== null) {
                 taken[segment.name] = part
@@ -79,7 +90,8 @@ function walk(
         return walk(segments, index + 1, parts, at, prefix)
     }
     if (part === undefined) return null
-    if (segment.kind === 'static' && part !== segment.name) return null
+    if (segment.kind === 'static' ? part !== segment.name : !takeable)
+        return null
     const params = walk(segments, index + 1, parts, at + 1, prefix)
     if (params !== null && segment.kind === 'required')
         params[segment.name] = part

package/src/shared/routePattern.ts

@@ -17,29 +17,78 @@ export type Segment = {
     kind: SegmentKind
     /** The literal text for a static segment, the param name for the other three. */
     name: string
+    /** 23.26 — the matcher a dynamic segment names after `=`, or `undefined` where it names none. */
+    matcher: string | undefined
+    /** 30.34, 30.35 — what a part must match to be taken: the matcher's, or the period default. */
+    accepts: RegExp
 }
 
+/** 30.34, 30.36 — what a segment naming no matcher takes: a part carrying no period. */
+const PERIODLESS = /^[^.]+$/
+
+// A segment naming a matcher, parsed with no table to resolve it in, takes nothing: only a route
+// table's own rows say which regex a name stands for (23.26), and a reader that only builds an
+// address or compares shapes never walks one.
+const UNRESOLVED = /(?!)/
+
 /**
  * A route literal split into its segments, each classified by kind.
  *
- * `[...rest]`, `[[optional]]`, `[required]`, or a literal. Ordered longest-first: `[[a]]` is a
- * `[a]` with another bracket round it, so testing the short form first matches both.
+ * `[...rest]`, `[[optional]]`, `[required]`, or a literal, each dynamic one optionally naming a
+ * matcher after `=`, compiled from `matchers` — each name's anchored source, as the build wrote it
+ * into the row (23.26) — where a route table hands its row's. Ordered
+ * longest-first: `[[a]]` is a `[a]` with another bracket round it, so testing the short form first
+ * matches both.
  */
-export function parseRoutePattern(pattern: string): Segment[] {
+export function parseRoutePattern(
+    pattern: string,
+    matchers?: Record<string, string>,
+): Segment[] {
     const out: Segment[] = []
     for (const raw of pattern.split('/')) {
         if (raw === '') continue
-        if (raw.startsWith('[[') && raw.endsWith(']]'))
-            out.push({ kind: 'optional', name: raw.slice(2, -2) })
-        else if (raw.startsWith('[...') && raw.endsWith(']'))
-            out.push({ kind: 'rest', name: raw.slice(4, -1) })
-        else if (raw.startsWith('[') && raw.endsWith(']'))
-            out.push({ kind: 'required', name: raw.slice(1, -1) })
-        else out.push({ kind: 'static', name: raw })
+        let kind: SegmentKind = 'static'
+        let body = raw
+        if (raw.startsWith('[[') && raw.endsWith(']]')) {
+            kind = 'optional'
+            body = raw.slice(2, -2)
+        } else if (raw.startsWith('[...') && raw.endsWith(']')) {
+            kind = 'rest'
+            body = raw.slice(4, -1)
+        } else if (raw.startsWith('[') && raw.endsWith(']')) {
+            kind = 'required'
+            body = raw.slice(1, -1)
+        }
+        const split = kind === 'static' ? -1 : body.indexOf('=')
+        const matcher = split === -1 ? undefined : body.slice(split + 1)
+        out.push({
+            kind,
+            name: split === -1 ? body : body.slice(0, split),
+            matcher,
+            accepts:
+                matcher === undefined
+                    ? PERIODLESS
+                    : matchers === undefined
+                      ? UNRESOLVED
+                      : resolvedIn(matchers, matcher, pattern),
+        })
     }
     return out
 }
 
+function resolvedIn(
+    matchers: Record<string, string>,
+    matcher: string,
+    pattern: string,
+): RegExp {
+    const source = matchers[matcher]
+    if (source === undefined)
+        throw new Error(
+            `abide: the route table's row for ${pattern} carries no matcher ${matcher}, which the build writes beside every segment naming one. RULEBOOK 23.26.`,
+        )
+    return new RegExp(source)
+}
+
 /**
  * A `sort` comparator over two parsed patterns: negative where `a` is the more specific.
  *
@@ -99,12 +148,15 @@ export function coversRoute(outer: Segment[], route: Segment[]): boolean {
  * which page an address resolves to, so it is here with `compareRoutes` rather than written out
  * beside each table: the server's boot and the client router's start compile through one call.
  */
-export function rankRoutes<T extends { pattern: string }>(
-    rows: T[],
-): (T & { segments: Segment[] })[] {
+export function rankRoutes<
+    T extends { pattern: string; matchers?: Record<string, string> },
+>(rows: T[]): (T & { segments: Segment[] })[] {
     const ranked: (T & { segments: Segment[] })[] = []
     for (const row of rows)
-        ranked.push({ ...row, segments: parseRoutePattern(row.pattern) })
+        ranked.push({
+            ...row,
+            segments: parseRoutePattern(row.pattern, row.matchers ?? {}),
+        })
     ranked.sort((a, b) => compareRoutes(a.segments, b.segments))
     return ranked
 }