@abide/abide 0.117.1 → 0.118.0

package/docs/abide.md

@@ -310,7 +310,7 @@ A file's path below `src` is its address. Nothing else names a route.
 | --- | --- |
 | `src/index.abide` | `/` |
 | `src/contacts/index.abide` | `/contacts` |
-| `src/contacts/listContacts.ts` | `GET /contacts/listContacts`, the handler its default export declares |
+| `src/contacts/listContacts.handler.ts` | `GET /contacts/listContacts`, the handler its default export declares |
 | `src/contacts/lib/ContactList.abide` | no address: a component the pages import |
 | `src/contacts/lib/ContactList.test.ts` | no address: what `bun test` runs |
 
@@ -335,7 +335,7 @@ Any other file beside the pages fails the build, so listing a directory lists it
 ```abide src/contacts/lib/ContactList.abide
 <script>
 import { reactive } from '@abide/abide'
-import listContacts from '../listContacts.ts'
+import listContacts from '../listContacts.handler.ts'
 
 const contacts = reactive(() => listContacts())
 </script>
@@ -347,7 +347,7 @@ const contacts = reactive(() => listContacts())
 </ul>
 ```
 
-```ts src/contacts/listContacts.ts
+```ts src/contacts/listContacts.handler.ts
 import { GET } from '@abide/abide/server'
 import { CONTACTS } from './lib/CONTACTS.server.ts'
 
@@ -360,7 +360,7 @@ export default GET(async () => {
 
 ```ts src/contacts/lib/ContactList.test.ts
 import { expect, test } from 'bun:test'
-import listContacts from '../listContacts.ts'
+import listContacts from '../listContacts.handler.ts'
 
 test('the handler the list reads answers with every contact', async () => {
     const contacts = await listContacts()
@@ -372,7 +372,7 @@ test('the handler the list reads answers with every contact', async () => {
 })
 ```
 
-`listContacts.ts` runs on the server. The list imports it like any module, and the browser is sent a call under the same name in its place, so there is no `fetch`, no route to register, and no second copy of the contact type.
+`listContacts.handler.ts` runs on the server. The list imports it like any module, and the browser is sent a call under the same name in its place, so there is no `fetch`, no route to register, and no second copy of the contact type.
 
 The test imports the same handler and calls it, in process. A handler only one page calls can live in that page's `<script server>` instead. See [Talk to the server](/guide/talk-to-the-server.md).
 
@@ -383,7 +383,7 @@ The test imports the same handler and calls it, in process. A handler only one p
 ```abide src/contacts/lib/PageTiming.abide
 <script>
 import { reactive } from '@abide/abide'
-import listContacts from '../listContacts.ts'
+import listContacts from '../listContacts.handler.ts'
 
 let pageComplete = reactive('—')
 let contactsAnswered = reactive('—')
@@ -473,7 +473,7 @@ Naming `starred` in the markup reads it and follows it from then on. Assigning t
 ```abide src/contacts/lib/ContactNote.abide
 <script>
 import { reactive } from '@abide/abide'
-import listContacts from '../listContacts.ts'
+import listContacts from '../listContacts.handler.ts'
 
 // Owned, derived, loaded, and waiting for its first write.
 let draft = reactive('')
@@ -1085,15 +1085,15 @@ Every server call in this chapter is a handler: a function wrapped in `GET`, `PO
 
 ## A handler file answers at its own path
 
-A `.ts` file beside the pages is a handler file. Its default export is the handler, and its path below `src` is the address it answers on.
+A file named `<name>.handler.ts` beside the pages is a handler file. Its default export is the handler, and its path below `src` is the address it answers on.
 
 | File below `src` | Answers on |
 | --- | --- |
-| `**/<name>.ts` | its directory's route, then `<name>` |
-| `deals/getDeal.ts` | `GET /deals/getDeal` |
-| `users/getUser.ts` | `GET /users/getUser` |
-| `health.ts` | `GET /health` |
-| `media/[id]/save.ts` | `POST /media/42/save`, with `id` in its args |
+| `**/<name>.handler.ts` | its directory's route, then `<name>` |
+| `deals/getDeal.handler.ts` | `GET /deals/getDeal` |
+| `users/getUser.handler.ts` | `GET /users/getUser` |
+| `health.handler.ts` | `GET /health` |
+| `media/[id]/save.handler.ts` | `POST /media/42/save`, with `id` in its args |
 | `media/[id]/lib/Comments.abide` | `/__abide/handlers/media/id/lib/Comments/addComment`, for the `addComment` its `<script server>` declares |
 
 A handler file exports its handler and nothing else. A page imports it, a script calls its address, and the CLI and MCP offer it as a command and a tool.
@@ -1105,7 +1105,7 @@ A handler file exports its handler and nothing else. A page imports it, a script
 ```abide src/deals/lib/DealDetail.abide
 <script>
 import { reactive } from '@abide/abide'
-import getDeal from '../getDeal.ts'
+import getDeal from '../getDeal.handler.ts'
 
 let id = reactive('d1')
 
@@ -1125,7 +1125,7 @@ const deal = reactive(() => getDeal({ id }))
 </ul>
 ```
 
-```ts src/deals/getDeal.ts
+```ts src/deals/getDeal.handler.ts
 import { refuse } from '@abide/abide'
 import { GET } from '@abide/abide/server'
 import { DEALS } from './lib/DEALS.server.ts'
@@ -1143,7 +1143,7 @@ export default GET(
 
 ```ts src/deals/lib/DealDetail.test.ts
 import { expect, test } from 'bun:test'
-import getDeal from '../getDeal.ts'
+import getDeal from '../getDeal.handler.ts'
 
 test('the handler answers the deal its args name', async () => {
     const deal = await getDeal({ id: 'd2' })
@@ -1226,7 +1226,7 @@ It still answers over http, below `/__abide/handlers` at its file's path and the
 ```abide src/deals/lib/NewDeal.abide
 <script>
 import { type Issues, reactive } from '@abide/abide'
-import createDeal from '../createDeal.ts'
+import createDeal from '../createDeal.handler.ts'
 
 type NewDeal = { name: string; company: string; amount: number }
 
@@ -1261,7 +1261,7 @@ async function add() {
 </ul>
 ```
 
-```ts src/deals/createDeal.ts
+```ts src/deals/createDeal.handler.ts
 import { jsonSchema } from '@abide/abide'
 import { POST } from '@abide/abide/server'
 import { DEALS } from './lib/DEALS.server.ts'
@@ -1341,8 +1341,8 @@ Two presses of Add inside one flight send one request and write one deal, and bo
 ```abide src/deals/lib/DealStage.abide
 <script>
 import { reactive } from '@abide/abide'
-import getDeal from '../getDeal.ts'
-import moveDeal from '../moveDeal.ts'
+import getDeal from '../getDeal.handler.ts'
+import moveDeal from '../moveDeal.handler.ts'
 
 let id = reactive('d2')
 let refusal = reactive('')
@@ -1381,7 +1381,7 @@ async function move(stage: string) {
 <p class="status">{refusal}</p>
 ```
 
-```ts src/deals/moveDeal.ts
+```ts src/deals/moveDeal.handler.ts
 import { jsonSchema, refuse } from '@abide/abide'
 import { PATCH } from '@abide/abide/server'
 import { DEALS } from './lib/DEALS.server.ts'
@@ -1409,7 +1409,7 @@ export default PATCH(
 
 ```ts src/deals/lib/DealStage.test.ts
 import { expect, test } from 'bun:test'
-import moveDeal from '../moveDeal.ts'
+import moveDeal from '../moveDeal.handler.ts'
 
 test('a closed deal is refused by name, with its stage as data', async () => {
     try {
@@ -1440,7 +1440,7 @@ Every refusal is a `Failed<Name, Data>`, in process and over the wire alike. The
 
 ```abide src/deals/lib/ExportDeals.abide
 <script>
-import exportDeals from '../exportDeals.ts'
+import exportDeals from '../exportDeals.handler.ts'
 </script>
 
 <div class="row">
@@ -1448,7 +1448,7 @@ import exportDeals from '../exportDeals.ts'
 </div>
 ```
 
-```ts src/deals/exportDeals.ts
+```ts src/deals/exportDeals.handler.ts
 import { GET } from '@abide/abide/server'
 import { DEALS } from './lib/DEALS.server.ts'
 
@@ -1466,7 +1466,7 @@ export default GET(
 
 ```ts src/deals/lib/ExportDeals.test.ts
 import { expect, test } from 'bun:test'
-import exportDeals from '../exportDeals.ts'
+import exportDeals from '../exportDeals.handler.ts'
 
 test('the export answers a CSV file', async () => {
     const file = await exportDeals()
@@ -1504,11 +1504,11 @@ Every answer carries headers you did not write:
 ```
 abide routes
 GET    /deals                       deals/index.abide
-POST   /deals/createDeal            deals/createDeal.ts
-GET    /deals/exportDeals           deals/exportDeals.ts
-GET    /deals/getDeal               deals/getDeal.ts
-GET    /deals/listDeals             deals/listDeals.ts
-PATCH  /deals/moveDeal              deals/moveDeal.ts
+POST   /deals/createDeal            deals/createDeal.handler.ts
+GET    /deals/exportDeals           deals/exportDeals.handler.ts
+GET    /deals/getDeal               deals/getDeal.handler.ts
+GET    /deals/listDeals             deals/listDeals.handler.ts
+PATCH  /deals/moveDeal              deals/moveDeal.handler.ts
 ```
 
 `abide routes [--json]` prints each address, its method and the file answering it, with every private handler marked `(private)`. With `--json` it prints the same as one document.
@@ -1520,7 +1520,7 @@ PATCH  /deals/moveDeal              deals/moveDeal.ts
 ```abide src/deals/lib/Pipeline.abide
 <script>
 import { reactive, refresh } from '@abide/abide'
-import listDeals from '../listDeals.ts'
+import listDeals from '../listDeals.handler.ts'
 
 const deals = reactive(() => listDeals())
 
@@ -1544,7 +1544,7 @@ const total = reactive(() => {
 </ul>
 ```
 
-```ts src/deals/listDeals.ts
+```ts src/deals/listDeals.handler.ts
 import { GET } from '@abide/abide/server'
 import { DEALS } from './lib/DEALS.server.ts'
 
@@ -1561,7 +1561,7 @@ export default GET(
 ```ts src/deals/lib/Pipeline.test.ts
 import { expect, test } from 'bun:test'
 import { reactive, refresh } from '@abide/abide'
-import listDeals from '../listDeals.ts'
+import listDeals from '../listDeals.handler.ts'
 
 test('a refresh is busy and still ready; a first load is not', async () => {
     const deals = reactive(() => listDeals())
@@ -1620,7 +1620,7 @@ import StageValue from './StageValue.abide'
 ```abide src/pipeline/lib/StageCount.abide
 <script>
 import { reactive } from '@abide/abide'
-import getStage from '../getStage.ts'
+import getStage from '../getStage.handler.ts'
 import { STAGES } from './STAGES.ts'
 
 let stage = reactive('lead')
@@ -1642,7 +1642,7 @@ const totals = reactive(() => getStage({ stage }))
 ```abide src/pipeline/lib/StageValue.abide
 <script>
 import { reactive } from '@abide/abide'
-import getStage from '../getStage.ts'
+import getStage from '../getStage.handler.ts'
 import { dollars } from './dollars.ts'
 import { STAGES } from './STAGES.ts'
 
@@ -1663,7 +1663,7 @@ const totals = reactive(() => getStage({ stage }))
 </ul>
 ```
 
-```ts src/pipeline/getStage.ts
+```ts src/pipeline/getStage.handler.ts
 import { GET } from '@abide/abide/server'
 import { DEALS } from './lib/DEALS.server.ts'
 import { LOADS } from './lib/LOADS.server.ts'
@@ -1690,7 +1690,7 @@ export default GET(
 ```ts src/pipeline/lib/StageTiles.test.ts
 import { expect, test } from 'bun:test'
 import { mount } from '@abide/harness/abide'
-import getStage from '../getStage.ts'
+import getStage from '../getStage.handler.ts'
 import StageTiles from './StageTiles.abide'
 import { LOADS } from './LOADS.server.ts'
 
@@ -1732,7 +1732,7 @@ A body with a parameter is a keyed value: one entry per set of arguments, held.
 ```abide src/pipeline/lib/Forecast.abide
 <script>
 import { reactive } from '@abide/abide'
-import getForecast from '../getForecast.ts'
+import getForecast from '../getForecast.handler.ts'
 import { dollars } from './dollars.ts'
 
 const forecast = reactive(() => getForecast())
@@ -1754,7 +1754,7 @@ const reloading = reactive(() => forecast.busy() && forecast.ready())
 </div>
 ```
 
-```ts src/pipeline/getForecast.ts
+```ts src/pipeline/getForecast.handler.ts
 import { GET } from '@abide/abide/server'
 import { DEALS } from './lib/DEALS.server.ts'
 import { LOADS } from './lib/LOADS.server.ts'
@@ -1836,8 +1836,8 @@ Press Mark stale and then Reload now, and the forecast blanks between the two. T
 
 ```abide src/pipeline/lib/StageBoard.abide
 <script>
-import getStage from '../getStage.ts'
-import winDeal from '../winDeal.ts'
+import getStage from '../getStage.handler.ts'
+import winDeal from '../winDeal.handler.ts'
 import StageTile from './StageTile.abide'
 import { STAGES } from './STAGES.ts'
 
@@ -1863,7 +1863,7 @@ async function win() {
 ```abide src/pipeline/lib/StageTile.abide
 <script>
 import { props, reactive } from '@abide/abide'
-import getStage from '../getStage.ts'
+import getStage from '../getStage.handler.ts'
 
 const { stage } = props<{ stage: string }>()
 const totals = reactive(() => getStage({ stage }))
@@ -1875,7 +1875,7 @@ const totals = reactive(() => getStage({ stage }))
 </li>
 ```
 
-```ts src/pipeline/winDeal.ts
+```ts src/pipeline/winDeal.handler.ts
 import { POST } from '@abide/abide/server'
 import { DEALS } from './lib/DEALS.server.ts'
 
@@ -1934,7 +1934,7 @@ The triggers also come as free functions, and those take a `Selection`: the set
 ```abide src/pipeline/lib/DealSearch.abide
 <script>
 import { reactive } from '@abide/abide'
-import searchDeals from '../searchDeals.ts'
+import searchDeals from '../searchDeals.handler.ts'
 
 let q = reactive('')
 const found = reactive(() => searchDeals({ q }), { debounce: 300 })
@@ -1951,7 +1951,7 @@ const found = reactive(() => searchDeals({ q }), { debounce: 300 })
 </ul>
 ```
 
-```ts src/pipeline/searchDeals.ts
+```ts src/pipeline/searchDeals.handler.ts
 import { GET } from '@abide/abide/server'
 import { DEALS } from './lib/DEALS.server.ts'
 import { LOADS } from './lib/LOADS.server.ts'
@@ -2020,7 +2020,7 @@ Every keystroke is a new `q`, and so a new key. `debounce: 300` holds the search
 ```abide src/pipeline/lib/DealFeed.abide
 <script>
 import { reactive } from '@abide/abide'
-import listDeals from '../listDeals.ts'
+import listDeals from '../listDeals.handler.ts'
 import { dollars } from './dollars.ts'
 
 const deals = reactive(() => listDeals())
@@ -2055,7 +2055,7 @@ function applyNextUpdate() {
 </div>
 ```
 
-```ts src/pipeline/listDeals.ts
+```ts src/pipeline/listDeals.handler.ts
 import { GET } from '@abide/abide/server'
 import { DEALS } from './lib/DEALS.server.ts'
 
@@ -2109,7 +2109,7 @@ Change the held value without `patch` and nothing on the page moves, because no
 ```abide src/pipeline/lib/DealPicker.abide
 <script>
 import { reactive } from '@abide/abide'
-import listDeals from '../listDeals.ts'
+import listDeals from '../listDeals.handler.ts'
 import DealDetail from './DealDetail.abide'
 import DealRow from './DealRow.abide'
 
@@ -2145,7 +2145,7 @@ let selected = reactive.share('selectedDeal', () => reactive(''))
 ```abide src/pipeline/lib/DealDetail.abide
 <script>
 import { reactive } from '@abide/abide'
-import listDeals from '../listDeals.ts'
+import listDeals from '../listDeals.handler.ts'
 
 const deals = reactive(() => listDeals())
 const selected = reactive.share('selectedDeal', () => reactive(''))
@@ -2193,7 +2193,7 @@ Use the value `reactive.share` returns, and no other name. A value lives in the
 ```abide src/pipeline/lib/DealNote.abide
 <script>
 import { reactive, watch } from '@abide/abide'
-import saveNote from '../saveNote.ts'
+import saveNote from '../saveNote.handler.ts'
 
 let note = reactive('Wants a quote by Friday.')
 let saved = reactive('Wants a quote by Friday.')
@@ -2220,7 +2220,7 @@ watch(() => {
 </ul>
 ```
 
-```ts src/pipeline/saveNote.ts
+```ts src/pipeline/saveNote.handler.ts
 import { POST } from '@abide/abide/server'
 import { LOADS } from './lib/LOADS.server.ts'
 import { NOTES } from './lib/NOTES.server.ts'
@@ -2313,8 +2313,8 @@ let view = reactive('board', { store: preferenceStore('view') })
 
 ```ts src/pipeline/lib/preferenceStore.ts
 import type { Store } from '@abide/abide'
-import getPreference from '../getPreference.ts'
-import setPreference from '../setPreference.ts'
+import getPreference from '../getPreference.handler.ts'
+import setPreference from '../setPreference.handler.ts'
 
 /** Where a preference lives between visits: both halves, or neither. */
 export function preferenceStore(name: string): Store<string> {
@@ -2330,7 +2330,7 @@ export function preferenceStore(name: string): Store<string> {
 }
 ```
 
-```ts src/pipeline/getPreference.ts
+```ts src/pipeline/getPreference.handler.ts
 import { GET } from '@abide/abide/server'
 import { PREFERENCES } from './lib/PREFERENCES.server.ts'
 
@@ -2345,7 +2345,7 @@ export default GET(
 )
 ```
 
-```ts src/pipeline/setPreference.ts
+```ts src/pipeline/setPreference.handler.ts
 import { POST } from '@abide/abide/server'
 import { PREFERENCES } from './lib/PREFERENCES.server.ts'
 
@@ -2567,8 +2567,8 @@ A value keeps no past of its own. Where you want what came before, make the valu
 ```abide src/activity/lib/AccountFeed.abide
 <script>
 import { reactive } from '@abide/abide'
-import feed from '../feed.ts'
-import logToFeed from '../logToFeed.ts'
+import feed from '../feed.handler.ts'
+import logToFeed from '../logToFeed.handler.ts'
 
 const account = 'hopper-co'
 const entries = reactive(() => feed({ account }))
@@ -2600,7 +2600,7 @@ export const feeds = reactive((_account: { account: string }): Entry[] => [], {
 })
 ```
 
-```ts src/activity/feed.ts
+```ts src/activity/feed.handler.ts
 import { GET } from '@abide/abide/server'
 import { feeds } from './lib/feeds.ts'
 
@@ -2608,7 +2608,7 @@ import { feeds } from './lib/feeds.ts'
 export default GET(feeds, { description: "An account's activity feed." })
 ```
 
-```ts src/activity/logToFeed.ts
+```ts src/activity/logToFeed.handler.ts
 import { POST } from '@abide/abide/server'
 import { feeds } from './lib/feeds.ts'
 
@@ -2674,7 +2674,7 @@ The feed lives in memory. A restart starts it empty, and each instance of the ap
 ```abide src/activity/lib/ActivityHistory.abide
 <script>
 import { reactive, refresh } from '@abide/abide'
-import olderActivity from '../olderActivity.ts'
+import olderActivity from '../olderActivity.handler.ts'
 
 const entries = reactive(() => olderActivity())
 </script>
@@ -2691,7 +2691,7 @@ const entries = reactive(() => olderActivity())
 </div>
 ```
 
-```ts src/activity/olderActivity.ts
+```ts src/activity/olderActivity.handler.ts
 import { GET } from '@abide/abide/server'
 
 const OLDER = [
@@ -2715,7 +2715,7 @@ export default GET(
 
 ```ts src/activity/lib/ActivityHistory.test.ts
 import { expect, test } from 'bun:test'
-import olderActivity from '../olderActivity.ts'
+import olderActivity from '../olderActivity.handler.ts'
 
 test('the first entry is in hand while the rest are still read', async () => {
     const entries = olderActivity()
@@ -2746,7 +2746,7 @@ A page rendered on the server is not held for an unfinished stream. What the str
 ```abide src/activity/lib/CsvExport.abide
 <script>
 import { reactive } from '@abide/abide'
-import exportCsv from '../exportCsv.ts'
+import exportCsv from '../exportCsv.handler.ts'
 
 const csv = reactive(async () => (await exportCsv.raw()).text())
 </script>
@@ -2759,7 +2759,7 @@ const csv = reactive(async () => (await exportCsv.raw()).text())
 </div>
 ```
 
-```ts src/activity/exportCsv.ts
+```ts src/activity/exportCsv.handler.ts
 import { bytes, GET } from '@abide/abide/server'
 
 const ENCODER = new TextEncoder()
@@ -2819,7 +2819,7 @@ A stream whose first chunk is binary is sent as bytes without the helper. `bytes
 ```abide src/activity/lib/Wallboard.abide
 <script>
 import { reactive } from '@abide/abide'
-import ticker from '../ticker.ts'
+import ticker from '../ticker.handler.ts'
 
 // A plain request, as a wallboard sends it: no `Accept` asks for events.
 const answer = reactive(async () => {
@@ -2835,7 +2835,7 @@ const answer = reactive(async () => {
 <pre class="rounded-md border border-rule bg-raised p-3">{answer.body}</pre>
 ```
 
-```ts src/activity/ticker.ts
+```ts src/activity/ticker.handler.ts
 import { GET, sse } from '@abide/abide/server'
 
 const MOVES = [
@@ -2912,10 +2912,11 @@ The CRM outgrows one page. This chapter adds a page per company, the chrome they
 | File | Answers on |
 | --- | --- |
 | `src/companies/index.abide` | `/companies` |
-| `src/companies/[id].abide` | `/companies/hopper-and-co`, and every other id |
+| `src/companies/[id=SLUG].abide` | `/companies/hopper-and-co`, and every other id |
+| `src/companies/SLUG.param.ts` | no address: it says what a segment naming `SLUG` takes |
 | `src/companies/layout.abide` | no address: it wraps every page at `/companies` and below |
 | `src/companies/error.abide` | no address: it answers when a page below it fails |
-| `src/companies/getCompany.ts` | `GET /companies/getCompany` |
+| `src/companies/getCompany.handler.ts` | `GET /companies/getCompany` |
 
 An `**/index.abide` answers its directory's own address, and any other `**/<name>.abide` adds its name. A part of the path in brackets is a value the page reads:
 
@@ -2925,9 +2926,9 @@ An `**/index.abide` answers its directory's own address, and any other `**/<name
 | `[[name]]` | one segment or none | text, absent when nothing matched |
 | `[...name]` | every remaining segment | a list, empty when nothing matched |
 
-## `[id].abide` answers for every company
+## `[id=SLUG].abide` answers for every company
 
-**`[id].abide` — one file for every company** — Two companies, one page file. Pick one: the address changes, and the page loads the company the address names.
+**`[id=SLUG].abide` — one file for every company** — Two companies, one page file. Pick one: the address changes, and the page loads the company the address names.
 
 ```abide src/companies/lib/CompanyPages.abide
 <script>
@@ -2936,7 +2937,7 @@ import { reactive, url } from '@abide/abide'
 const IDS = ['analytical-engines', 'hopper-and-co']
 
 let open = reactive('hopper-and-co')
-const address = reactive(() => url('/companies/[id]', { id: open }))
+const address = reactive(() => url('/companies/[id=SLUG]', { id: open }))
 </script>
 
 <div class="tabs">
@@ -2950,10 +2951,10 @@ const address = reactive(() => url('/companies/[id]', { id: open }))
     class="h-60 w-full rounded-md border border-rule"></iframe>
 ```
 
-```abide src/companies/[id].abide
+```abide src/companies/[id=SLUG].abide
 <script>
 import { reactive, route } from '@abide/abide'
-import getCompany from './getCompany.ts'
+import getCompany from './getCompany.handler.ts'
 import CompanyTabs from './lib/CompanyTabs.abide'
 
 const company = reactive(() => getCompany({ id: route.params.id }))
@@ -2995,10 +2996,97 @@ test('one file answers for every company, reading its id', async () => {
 
 | Name | What it does for the CRM |
 | --- | --- |
-| `route.name` | the pattern that matched, `/companies/[id]` for every company, so a log line keys on the page rather than on each address |
+| `route.name` | the pattern that matched, `/companies/[id=SLUG]` for every company, so a log line keys on the page rather than on each address |
 | `Params` | what the segments matched; a query string is never in it |
 | `RouteParams<P>` | the type `route.params` has in a page or layout filed under `P`, so `id` is text and a key the route lacks is an error. A component under `lib/` has no route of its own and reads the loose `Params`: pass it the value as a prop, or narrow it with `RouteParams<'/…'>` |
 
+## A param file says what an id looks like
+
+**`SLUG.param.ts` — an address that cannot be an id never reaches the page** — A rep pastes a company's name where its id goes. No id has a capital or a space, so no page takes the address, and nothing asks the database for it.
+
+```abide src/companies/lib/PastedName.abide
+<script>
+import { reactive, url } from '@abide/abide'
+
+const PASTED = ['hopper-and-co', 'Hopper & Co']
+
+let open = reactive('Hopper & Co')
+const address = reactive(() => url('/companies/[id=SLUG]', { id: open }))
+</script>
+
+<div class="tabs">
+    {#for id of PASTED}
+        <button aria-selected={open === id}
+            onclick={() => (open = id)}>{id}</button>
+    {/for}
+</div>
+<p class="status">{address}</p>
+<iframe src={address} title="An address the company page may not take"
+    class="h-48 w-full rounded-md border border-rule"></iframe>
+```
+
+```ts src/companies/SLUG.param.ts
+// A company's id: lowercase words and digits, joined by hyphens.
+export const SLUG = /[a-z0-9-]+/
+```
+
+```abide src/companies/[id=SLUG].abide
+<script>
+import { reactive, route } from '@abide/abide'
+import getCompany from './getCompany.handler.ts'
+import CompanyTabs from './lib/CompanyTabs.abide'
+
+const company = reactive(() => getCompany({ id: route.params.id }))
+</script>
+
+<head><title>{company.name} — CRM</title></head>
+
+<h2 class="text-heading font-semibold"
+    style:view-transition-name="company-{route.params.id}">{company.name}</h2>
+<ul class="fields">
+    <li><span>contact</span><strong>{company.contact}</strong></li>
+    <li><span>pipeline</span><strong>{company.pipeline}</strong></li>
+</ul>
+<CompanyTabs />
+
+<style>
+::view-transition-group(*) { animation-duration: 0.5s; }
+</style>
+```
+
+```ts src/companies/Matcher.test.ts
+import { expect, test } from 'bun:test'
+import { createApp } from '@abide/abide/server'
+import { COMPANIES } from './lib/COMPANIES.server.ts'
+
+test('the company page takes every id the CRM has, and no name', async () => {
+    await using app = await createApp()
+    for (const { id } of COMPANIES) {
+        const answer = await app.fetch(
+            new Request(`http://crm.invalid/companies/${id}`),
+        )
+        expect(answer.status).toBe(200)
+        await answer.body?.cancel()
+    }
+    const pasted = await app.fetch(
+        new Request('http://crm.invalid/companies/Hopper%20%26%20Co'),
+    )
+    expect(pasted.status).toBe(404)
+})
+```
+
+A segment names its matcher after an `=`. `[id=SLUG]` takes a part only where the whole of it, decoded, matches the `SLUG` in `SLUG.param.ts`, found beside the page or in the nearest directory above it. A part it refuses goes to the next route that could answer the address. The companies have none, so `Hopper & Co` is a 404, painted by `error.abide`.
+
+| Named | Matches |
+| --- | --- |
+| `[name=NAME]` | one segment the matcher takes |
+| `[[name=NAME]]` | one segment the matcher takes, or none |
+| `[...name=NAME]` | every remaining segment, each one the matcher takes |
+
+The build reads a param file without running it, so it holds one `export const` named as the file, a regular expression with no flags, and no import. A pattern that repeats a group that itself repeats, or that refers back to a group, is refused: either can make one crafted address slow to test.
+
+A segment with no matcher never takes a part with a period in it, which is why `/favicon.ico` never reaches a company page. A matcher replaces that rule for its segment, so one that allows a period lets `url` write one too. `.` and `..` are never taken. Under `abide check`, a matcher that is a choice of words, `/deals|notes/`, types the param as those words in `route.params` and in `url`.
+
 ## A layout holds what the companies pages share
 
 **`layout.abide` — the header the companies pages share, built once** — The companies header holds a note for the call you are on. Type one, then open a company and come back: the page changes, and the note stays.
@@ -3057,7 +3145,7 @@ A package can ship pages too. `import '…' with { type: 'routes' }` in a file o
 
 ## A link names a route, and `url` fills it in
 
-The list links each company with `url('/companies/[id]', { id: company.id })`. You write the pattern a page is filed under rather than the address, and `url` fills in the segments. Leaving out a required one is a compile error, and a pattern no page is filed under is refused by `abide check`. A query goes last: `url('/companies', {}, { city: 'London' })`.
+The list links each company with `url('/companies/[id=SLUG]', { id: company.id })`. You write the pattern a page is filed under, matcher and all, rather than the address, and `url` fills in the segments. Leaving out a required one is a compile error, and a pattern no page is filed under is refused by `abide check`. A query goes last: `url('/companies', {}, { city: 'London' })`.
 
 | Name | What it does for the CRM |
 | --- | --- |
@@ -3137,7 +3225,7 @@ import { url } from '@abide/abide'
 ```abide src/companies/index.abide
 <script>
 import { reactive, url } from '@abide/abide'
-import listCompanies from './listCompanies.ts'
+import listCompanies from './listCompanies.handler.ts'
 
 const companies = reactive(() => listCompanies())
 </script>
@@ -3145,7 +3233,7 @@ const companies = reactive(() => listCompanies())
 <ul class="fields">
     {#for company of companies by company.id}
         <li><span>{company.city}</span>
-            <a href={url('/companies/[id]', { id: company.id })}
+            <a href={url('/companies/[id=SLUG]', { id: company.id })}
                 style:view-transition-name="company-{company.id}"
             >{company.name}</a></li>
     {/for}
@@ -3156,10 +3244,10 @@ const companies = reactive(() => listCompanies())
 </style>
 ```
 
-```abide src/companies/[id].abide
+```abide src/companies/[id=SLUG].abide
 <script>
 import { reactive, route } from '@abide/abide'
-import getCompany from './getCompany.ts'
+import getCompany from './getCompany.handler.ts'
 import CompanyTabs from './lib/CompanyTabs.abide'
 
 const company = reactive(() => getCompany({ id: route.params.id }))
@@ -3209,7 +3297,7 @@ const PAGES = [
     { label: 'All companies', address: url('/companies') },
     {
         label: 'Hopper & Co',
-        address: url('/companies/[id]', { id: 'hopper-and-co' }),
+        address: url('/companies/[id=SLUG]', { id: 'hopper-and-co' }),
     },
 ]
 
@@ -3275,10 +3363,10 @@ let note = reactive('')
 <slot/>
 ```
 
-```abide src/companies/[id].abide
+```abide src/companies/[id=SLUG].abide
 <script>
 import { reactive, route } from '@abide/abide'
-import getCompany from './getCompany.ts'
+import getCompany from './getCompany.handler.ts'
 import CompanyTabs from './lib/CompanyTabs.abide'
 
 const company = reactive(() => getCompany({ id: route.params.id }))
@@ -3329,7 +3417,7 @@ A `<head>` sits at the top level of a file, never inside a block. A `<title>`, a
 <script>
 import { reactive, url } from '@abide/abide'
 
-const PAGE = url('/companies/[id]', { id: 'hopper-and-co' })
+const PAGE = url('/companies/[id=SLUG]', { id: 'hopper-and-co' })
 
 let loads = reactive(1)
 </script>
@@ -3341,10 +3429,10 @@ let loads = reactive(1)
     class="h-60 w-full rounded-md border border-rule"></iframe>
 ```
 
-```abide src/companies/[id].abide
+```abide src/companies/[id=SLUG].abide
 <script>
 import { reactive, route } from '@abide/abide'
-import getCompany from './getCompany.ts'
+import getCompany from './getCompany.handler.ts'
 import CompanyTabs from './lib/CompanyTabs.abide'
 
 const company = reactive(() => getCompany({ id: route.params.id }))
@@ -3365,7 +3453,7 @@ const company = reactive(() => getCompany({ id: route.params.id }))
 </style>
 ```
 
-```ts src/companies/getCompany.ts
+```ts src/companies/getCompany.handler.ts
 import { GET, notFound } from '@abide/abide/server'
 import { COMPANIES } from './lib/COMPANIES.server.ts'
 
@@ -3419,7 +3507,7 @@ Nothing holds the document for a value. The page gets one turn to start its load
 import { url } from '@abide/abide'
 </script>
 
-<iframe src={url('/companies/[id]', { id: 'initech' })}
+<iframe src={url('/companies/[id=SLUG]', { id: 'initech' })}
     title="A company that is not there"
     class="h-48 w-full rounded-md border border-rule"></iframe>
 ```
@@ -3440,7 +3528,7 @@ const { failure } = props<{ failure: Failed<string, unknown> }>()
 {/if}
 ```
 
-```ts src/companies/getCompany.ts
+```ts src/companies/getCompany.handler.ts
 import { GET, notFound } from '@abide/abide/server'
 import { COMPANIES } from './lib/COMPANIES.server.ts'
 
@@ -3483,8 +3571,8 @@ The refusal has to come in the page's first turn to set the status. That is why
 ```abide src/companies/lib/ExportButton.abide
 <script>
 import { isFailed, reactive, refresh } from '@abide/abide'
-import exportCompanies from '../exportCompanies.ts'
-import reportedErrors from '../reportedErrors.ts'
+import exportCompanies from '../exportCompanies.handler.ts'
+import reportedErrors from '../reportedErrors.handler.ts'
 
 let told = reactive('—')
 const reported = reactive(() => reportedErrors())
@@ -3509,7 +3597,7 @@ async function runExport() {
 </ul>
 ```
 
-```ts src/companies/exportCompanies.ts
+```ts src/companies/exportCompanies.handler.ts
 import { POST } from '@abide/abide/server'
 
 /** Answers at /companies/exportCompanies; the export button calls it. */
@@ -3576,7 +3664,7 @@ test('the caller gets a bare 500, and onError gets the reason', async () => {
 
 ```abide src/companies/lib/SheetPreview.abide
 <script>
-import previewCompany from '../previewCompany.ts'
+import previewCompany from '../previewCompany.handler.ts'
 </script>
 
 <iframe src={previewCompany.url({ id: 'hopper-and-co' })}
@@ -3584,7 +3672,7 @@ import previewCompany from '../previewCompany.ts'
     class="h-48 w-full rounded-md border border-rule"></iframe>
 ```
 
-```ts src/companies/previewCompany.ts
+```ts src/companies/previewCompany.handler.ts
 import { GET, notFound, page, render } from '@abide/abide/server'
 import CompanySheet from './lib/CompanySheet.abide'
 import { COMPANIES } from './lib/COMPANIES.server.ts'
@@ -3677,8 +3765,8 @@ Everything in this chapter is in `src/account` of the chapter app, beside `src/c
 ```abide src/account/lib/SignIn.abide
 <script>
 import { principal, reactive } from '@abide/abide'
-import signIn from '../signIn.ts'
-import signOut from '../signOut.ts'
+import signIn from '../signIn.handler.ts'
+import signOut from '../signOut.handler.ts'
 
 let email = reactive('maya@crm.example')
 </script>
@@ -3694,7 +3782,7 @@ let email = reactive('maya@crm.example')
 </div>
 ```
 
-```ts src/account/signIn.ts
+```ts src/account/signIn.handler.ts
 import { principal, refuse } from '@abide/abide'
 import { onPrincipal, POST } from '@abide/abide/server'
 import { TEAM } from './lib/TEAM.server.ts'
@@ -3717,7 +3805,7 @@ onPrincipal((claims) => {
 })
 ```
 
-```ts src/account/signOut.ts
+```ts src/account/signOut.handler.ts
 import { principal } from '@abide/abide'
 import { POST } from '@abide/abide/server'
 
@@ -3765,7 +3853,7 @@ test('a request carrying the cookie is signed in', async () => {
 })
 ```
 
-`principal.set(claims)` seals the claims into an `HttpOnly` cookie, and every request that carries it is that member's. `principal.clear()` signs them out. Both run in a handler, because the cookie is written on its answer. The `onPrincipal` at the foot of `signIn.ts` is the next card's.
+`principal.set(claims)` seals the claims into an `HttpOnly` cookie, and every request that carries it is that member's. `principal.clear()` signs them out. Both run in a handler, because the cookie is written on its answer. The `onPrincipal` at the foot of `signIn.handler.ts` is the next card's.
 
 The answer also tells the browser the caller changed. Every tab of the site reads `principal` again, so the form's own button flips with nothing passed to it.
 
@@ -3801,7 +3889,7 @@ import SignInAs from './SignInAs.abide'
 </ul>
 ```
 
-```ts src/account/signIn.ts
+```ts src/account/signIn.handler.ts
 import { principal, refuse } from '@abide/abide'
 import { onPrincipal, POST } from '@abide/abide/server'
 import { TEAM } from './lib/TEAM.server.ts'
@@ -3898,7 +3986,7 @@ test('the server paints the density the cookie holds', async () => {
 ```abide src/account/lib/ContactCard.abide
 <script>
 import { principal, reactive, watch } from '@abide/abide'
-import getContact from '../getContact.ts'
+import getContact from '../getContact.handler.ts'
 import SignInAs from './SignInAs.abide'
 
 const contact = reactive(() => getContact())
@@ -3919,7 +4007,7 @@ const dealValue = () => contact.dealValue ?? 'admins only'
 </ul>
 ```
 
-```ts src/account/getContact.ts
+```ts src/account/getContact.handler.ts
 import { principal } from '@abide/abide'
 import { GET } from '@abide/abide/server'
 
@@ -3945,7 +4033,7 @@ export default GET(
 ```ts src/account/lib/ContactCard.test.ts
 import { expect, test } from 'bun:test'
 import { createApp } from '@abide/abide/server'
-import getContact from '../getContact.ts'
+import getContact from '../getContact.handler.ts'
 
 test('an admin reads the deal value', async () => {
     await using app = await createApp()
@@ -3976,7 +4064,7 @@ An answer read under one member is not read again on its own when another signs
 ```abide src/account/lib/ExportContacts.abide
 <script>
 import { reactive } from '@abide/abide'
-import exportContacts from '../exportContacts.ts'
+import exportContacts from '../exportContacts.handler.ts'
 import SignInAs from './SignInAs.abide'
 
 let status = reactive('')
@@ -4000,7 +4088,7 @@ async function exportAll() {
 </div>
 ```
 
-```ts src/account/exportContacts.ts
+```ts src/account/exportContacts.handler.ts
 import { principal, refuse } from '@abide/abide'
 import { POST } from '@abide/abide/server'
 import { CONTACTS } from '../contacts/lib/CONTACTS.server.ts'
@@ -4021,7 +4109,7 @@ export default POST(async () => CONTACTS, {
 ```ts src/account/lib/ExportContacts.test.ts
 import { expect, test } from 'bun:test'
 import { createApp } from '@abide/abide/server'
-import exportContacts from '../exportContacts.ts'
+import exportContacts from '../exportContacts.handler.ts'
 
 test('an admin exports every contact', async () => {
     await using app = await createApp()
@@ -4079,7 +4167,7 @@ Filed in the root `src/layout.abide`, a rung runs before routing, over every req
 ```abide src/account/lib/PartnerStatement.abide
 <script server>
 import { GET } from '@abide/abide/server'
-import getStatement from '../getStatement.ts'
+import getStatement from '../getStatement.handler.ts'
 
 // Another site's browser, asking for the statement under its own origin.
 const askAs = GET(
@@ -4114,7 +4202,7 @@ const allowed = reactive(() => askAs({ origin }))
 </ul>
 ```
 
-```ts src/account/getStatement.ts
+```ts src/account/getStatement.handler.ts
 import { GET } from '@abide/abide/server'
 
 /** Read from the bookkeeping partner's own pages, and from no one else's. */
@@ -4162,7 +4250,7 @@ abide answers the `OPTIONS` preflight a cross-origin `POST` sends, outside every
 ```abide src/account/lib/SalesReport.abide
 <script>
 import { reactive } from '@abide/abide'
-import salesReport from '../salesReport.ts'
+import salesReport from '../salesReport.handler.ts'
 
 const REGIONS = ['north', 'south']
 
@@ -4191,7 +4279,7 @@ function refusal() {
 </ul>
 ```
 
-```ts src/account/salesReport.ts
+```ts src/account/salesReport.handler.ts
 import { GET } from '@abide/abide/server'
 
 const BY_REGION: Record<string, { week: string; total: string }[]> = {
@@ -4218,7 +4306,7 @@ export default GET(
 
 ```ts src/account/lib/SalesReport.test.ts
 import { expect, test } from 'bun:test'
-import salesReport from '../salesReport.ts'
+import salesReport from '../salesReport.handler.ts'
 
 test('a report slower than the timeout runs, a row at a time', async () => {
     const rows = []
@@ -4261,7 +4349,7 @@ None of these is a rate limit. A caller sending many small, fast requests passes
 ```abide src/account/lib/SyncContact.abide
 <script>
 import { reactive } from '@abide/abide'
-import syncContact from '../syncContact.ts'
+import syncContact from '../syncContact.handler.ts'
 
 let status = reactive('')
 
@@ -4283,7 +4371,7 @@ async function sync() {
 </div>
 ```
 
-```ts src/account/syncContact.ts
+```ts src/account/syncContact.handler.ts
 import { refuse } from '@abide/abide'
 import { POST, reachable } from '@abide/abide/server'
 import { billingOrigin } from './lib/billing.server.ts'
@@ -4345,7 +4433,7 @@ The answer can be a minute old. The call that follows a `true` can still fail, a
 ```abide src/account/lib/AddContact.abide
 <script>
 import { reactive } from '@abide/abide'
-import addContact from '../addContact.ts'
+import addContact from '../addContact.handler.ts'
 
 let added = reactive<{ status: number; location: string | null }>()
 
@@ -4367,7 +4455,7 @@ async function add() {
 </ul>
 ```
 
-```ts src/account/addContact.ts
+```ts src/account/addContact.handler.ts
 import { POST, response } from '@abide/abide/server'
 
 let nextId = 4031
@@ -4516,7 +4604,7 @@ Everything in this chapter lands on one page of the CRM, `/ops`, under `src/ops`
 ```abide src/ops/lib/Retries.abide
 <script>
 import { reactive } from '@abide/abide'
-import getRetries from '../getRetries.ts'
+import getRetries from '../getRetries.handler.ts'
 
 const policy = reactive(() => getRetries())
 </script>
@@ -4527,7 +4615,7 @@ const policy = reactive(() => getRetries())
 </ul>
 ```
 
-```ts src/ops/getRetries.ts
+```ts src/ops/getRetries.handler.ts
 import { config, GET, onConfig } from '@abide/abide/server'
 
 // The default; a deployment's RETRIES overrides it.
@@ -4598,7 +4686,7 @@ onConfig(() => ({ RETRIES: 3 }), {
 ```abide src/ops/lib/Pool.abide
 <script>
 import { reactive } from '@abide/abide'
-import getPool from '../getPool.ts'
+import getPool from '../getPool.handler.ts'
 
 const times = reactive(() => getPool())
 </script>
@@ -4609,7 +4697,7 @@ const times = reactive(() => getPool())
 </ul>
 ```
 
-```ts src/ops/getPool.ts
+```ts src/ops/getPool.handler.ts
 import { GET, onStart } from '@abide/abide/server'
 import { pool } from './lib/pool.server.ts'
 
@@ -4742,7 +4830,7 @@ abide logs under `abide:`, so `DEBUG=abide:*` turns on the framework and nothing
 ```abide src/ops/lib/Sync.abide
 <script>
 import { reactive } from '@abide/abide'
-import syncContact from '../syncContact.ts'
+import syncContact from '../syncContact.handler.ts'
 
 let synced = reactive<{ trace: string; lines: string[] }>()
 
@@ -4765,7 +4853,7 @@ async function sync() {
 </ul>
 ```
 
-```ts src/ops/syncContact.ts
+```ts src/ops/syncContact.handler.ts
 import { log, POST, trace } from '@abide/abide/server'
 import { billing } from './lib/billing.ts'
 
@@ -4955,8 +5043,8 @@ watch(() => { if (online) refresh() })
 ```abide src/ops/lib/CallLog.abide
 <script>
 import { outbox, reactive } from '@abide/abide'
-import listCalls from '../listCalls.ts'
-import logCall from '../logCall.ts'
+import listCalls from '../listCalls.handler.ts'
+import logCall from '../logCall.handler.ts'
 
 const calls = listCalls()
 let note = reactive('')
@@ -4990,7 +5078,7 @@ function log() {
 </ul>
 ```
 
-```ts src/ops/logCall.ts
+```ts src/ops/logCall.handler.ts
 import { POST } from '@abide/abide/server'
 import { type Call, calls } from './lib/calls.ts'
 
@@ -5026,7 +5114,7 @@ test('a call logged with the network is saved, and nothing waits', async () => {
 })
 
 test('a call sent twice under one id is logged once', async () => {
-    const { default: logCall } = await import('../logCall.ts')
+    const { default: logCall } = await import('../logCall.handler.ts')
     const call = { id: 'again', note: 'Asked twice' }
     await logCall(call)
     await logCall(call)
@@ -5067,7 +5155,7 @@ A handler file already carries an address, a method, an argument type and a desc
 
 | Surface | Who reads it | Where |
 | --- | --- | --- |
-| `ui` | a page | `import searchContacts from './searchContacts.ts'` |
+| `ui` | a page | `import searchContacts from './searchContacts.handler.ts'` |
 | `openapi` | a generated client, an API gateway | `/__abide/openapi.json` |
 | `mcp` | a model | `/__abide/mcp` |
 | `cli` | a person or a script in a terminal | `abide call` |
@@ -5106,7 +5194,7 @@ async function readDocument() {
 {/if}
 ```
 
-```ts src/assistant/searchContacts.ts
+```ts src/assistant/searchContacts.handler.ts
 import { GET } from '@abide/abide/server'
 import { CONTACTS } from '../contacts/lib/CONTACTS.server.ts'
 
@@ -5205,7 +5293,7 @@ async function callAsAModel() {
 </ul>
 ```
 
-```ts src/assistant/searchContacts.ts
+```ts src/assistant/searchContacts.handler.ts
 import { GET } from '@abide/abide/server'
 import { CONTACTS } from '../contacts/lib/CONTACTS.server.ts'
 
@@ -5265,7 +5353,7 @@ abide mcp --url https://crm.example
 ```abide src/assistant/lib/WithheldExport.abide
 <script>
 import { reactive, url } from '@abide/abide'
-import exportContacts from '../exportContacts.ts'
+import exportContacts from '../exportContacts.handler.ts'
 
 let listed = reactive('—')
 let answers = reactive('—')
@@ -5295,7 +5383,7 @@ async function check() {
 </ul>
 ```
 
-```ts src/assistant/exportContacts.ts
+```ts src/assistant/exportContacts.handler.ts
 import { GET } from '@abide/abide/server'
 import { CONTACTS } from '../contacts/lib/CONTACTS.server.ts'
 
@@ -5340,7 +5428,7 @@ The export is not a tool, and its address still answers. `clients` decides what
 
 | Key | Set to `false` |
 | --- | --- |
-| `ui` | No page can import the handler: the import is a compile error naming it. The stand-in in `v1/messages.ts` sets it. |
+| `ui` | No page can import the handler: the import is a compile error naming it. The stand-in in `v1/messages.handler.ts` sets it. |
 | `openapi` | No operation in `/__abide/openapi.json`. |
 | `mcp` | No tool on `/__abide/mcp`, and none for the assistant. |
 | `cli` | Not callable with `abide call`. |
@@ -5354,7 +5442,7 @@ A handler that returns a whole `Response` starts with `mcp` and `cli` off, havin
 ```abide src/assistant/lib/AssistantChat.abide
 <script>
 import { reactive } from '@abide/abide'
-import askAssistant from '../askAssistant.ts'
+import askAssistant from '../askAssistant.handler.ts'
 
 const QUESTION = 'Which company is Ada at?'
 
@@ -5391,7 +5479,7 @@ const events = reactive(() =>
 </div>
 ```
 
-```ts src/assistant/askAssistant.ts
+```ts src/assistant/askAssistant.handler.ts
 import {
     type AssistantMessage,
     assistant,
@@ -5483,7 +5571,7 @@ test('the model calls the CRM search, through the app', async () => {
 ```abide src/assistant/lib/ClaudeApiRequest.abide
 <script>
 import { reactive } from '@abide/abide'
-import askClaude from '../askClaude.ts'
+import askClaude from '../askClaude.handler.ts'
 
 const QUESTION = 'Which company is Ada at?'
 
@@ -5508,7 +5596,7 @@ const events = reactive(() =>
 {/for}
 ```
 
-```ts src/assistant/askClaude.ts
+```ts src/assistant/askClaude.handler.ts
 import {
     type AssistantMessage,
     assistant,
@@ -5516,7 +5604,7 @@ import {
     POST,
     request,
 } from '@abide/abide/server'
-import standIn from './v1/messages.ts'
+import standIn from './v1/messages.handler.ts'
 
 export default POST(
     async function* ({ messages }: { messages: AssistantMessage[] }) {
@@ -5537,7 +5625,7 @@ export default POST(
 )
 ```
 
-```ts src/assistant/v1/messages.ts
+```ts src/assistant/v1/messages.handler.ts
 import { POST, sse } from '@abide/abide/server'
 
 // A stand-in for the Messages API, streaming back the body it was sent.
@@ -5626,8 +5714,8 @@ Leave `baseURL` out and the request goes to Anthropic. `claudeApi` reads no key
 ```abide src/assistant/lib/ClaudeCodeBridge.abide
 <script>
 import { reactive } from '@abide/abide'
-import askClaudeCode from '../askClaudeCode.ts'
-import bridge from '../bridge.ts'
+import askClaudeCode from '../askClaudeCode.handler.ts'
+import bridge from '../bridge.handler.ts'
 
 const QUESTION = 'Which company is Grace at?'
 
@@ -5674,7 +5762,7 @@ const answer = reactive(() => {
 </div>
 ```
 
-```ts src/assistant/bridge.ts
+```ts src/assistant/bridge.handler.ts
 import { claudeCode, GET } from '@abide/abide/server'
 
 // This browser's pairing, for as long as the page watches it.
@@ -5686,7 +5774,7 @@ export default GET(() => claudeCode.bridge(), {
 })
 ```
 
-```ts src/assistant/askClaudeCode.ts
+```ts src/assistant/askClaudeCode.handler.ts
 import {
     type AssistantMessage,
     assistant,
@@ -5821,7 +5909,7 @@ Each card is a file of the reports page, beside the test or the bench that prove
 ```abide src/reports/lib/PipelineSummary.abide
 <script>
 import { reactive } from '@abide/abide'
-import getSummary from '../getSummary.ts'
+import getSummary from '../getSummary.handler.ts'
 
 const summary = reactive(() => getSummary())
 </script>
@@ -5832,7 +5920,7 @@ const summary = reactive(() => getSummary())
 </ul>
 ```
 
-```ts src/reports/getSummary.ts
+```ts src/reports/getSummary.handler.ts
 import { GET } from '@abide/abide/server'
 import { DEALS } from './lib/DEALS.server.ts'
 
@@ -7696,9 +7784,9 @@ Transports: what is written in place rather than imported.
 
 | File | Declares | Served at | Rules |
 | --- | --- | --- | --- |
-| `users/getUser.ts` | `export default GET(…)` | `/users/getUser` | [16.2](/rulebook#16.2), [16.73](/rulebook#16.73), [19.1](/rulebook#19.1), [19.20](/rulebook#19.20), [23.14](/rulebook#23.14) |
-| `health.ts` | `export default GET(…)` | `/health` | [16.2](/rulebook#16.2), [23.14](/rulebook#23.14) |
-| `media/[id]/save.ts` | `export default POST(…)` | `/media/[id]/save`, `id` reaching its `Args` | [16.2](/rulebook#16.2), [16.65](/rulebook#16.65), [16.66](/rulebook#16.66), [16.67](/rulebook#16.67), [16.69](/rulebook#16.69) |
+| `users/getUser.handler.ts` | `export default GET(…)` | `/users/getUser` | [16.2](/rulebook#16.2), [16.73](/rulebook#16.73), [19.1](/rulebook#19.1), [19.20](/rulebook#19.20), [23.14](/rulebook#23.14) |
+| `health.handler.ts` | `export default GET(…)` | `/health` | [16.2](/rulebook#16.2), [23.14](/rulebook#23.14) |
+| `media/[id]/save.handler.ts` | `export default POST(…)` | `/media/[id]/save`, `id` reaching its `Args` | [16.2](/rulebook#16.2), [16.65](/rulebook#16.65), [16.66](/rulebook#16.66), [16.67](/rulebook#16.67), [16.69](/rulebook#16.69) |
 | `media/[id]/lib/Comments.abide` | `const addComment = POST(…)` in its `<script server>` | `/__abide/handlers/media/id/lib/Comments/addComment` | [16.70](/rulebook#16.70), [16.71](/rulebook#16.71), [16.72](/rulebook#16.72) |
 
 ## Headers abide generates
@@ -7872,14 +7960,14 @@ Generated surfaces: what is written in place rather than imported.
 
 | Name | Signature | Meaning | Rules |
 | --- | --- | --- | --- |
-| `/__abide/openapi.json` | `GET` | The generated OpenAPI document. | [19.21](/rulebook#19.21), [19.22](/rulebook#19.22), [20.5](/rulebook#20.5), [20.6](/rulebook#20.6), [20.7](/rulebook#20.7), [20.8](/rulebook#20.8), [20.11](/rulebook#20.11), [20.13](/rulebook#20.13), [20.15](/rulebook#20.15), [36.7](/rulebook#36.7) |
+| `/__abide/openapi.json` | `GET` | The generated OpenAPI document. | [19.21](/rulebook#19.21), [19.22](/rulebook#19.22), [20.5](/rulebook#20.5), [20.6](/rulebook#20.6), [20.7](/rulebook#20.7), [20.8](/rulebook#20.8), [20.11](/rulebook#20.11), [20.13](/rulebook#20.13), [20.15](/rulebook#20.15), [20.23](/rulebook#20.23), [36.7](/rulebook#36.7) |
 | `OpenApiDocument` | `JsonValue` | OpenAPI 3.1, whose schema dialect is `JsonSchema`. | [20.6](/rulebook#20.6) |
 
 ## MCP
 
 | Name | Signature | Meaning | Rules |
 | --- | --- | --- | --- |
-| `/__abide/mcp` | `POST` | The streamable-http MCP endpoint. | [19.21](/rulebook#19.21), [19.22](/rulebook#19.22), [20.5](/rulebook#20.5), [20.7](/rulebook#20.7), [20.8](/rulebook#20.8), [20.9](/rulebook#20.9), [20.10](/rulebook#20.10), [20.12](/rulebook#20.12), [20.13](/rulebook#20.13), [20.14](/rulebook#20.14), [20.16](/rulebook#20.16), [20.17](/rulebook#20.17), [20.19](/rulebook#20.19), [20.20](/rulebook#20.20), [20.21](/rulebook#20.21), [20.22](/rulebook#20.22), [36.7](/rulebook#36.7), [16.78](/rulebook#16.78) |
+| `/__abide/mcp` | `POST` | The streamable-http MCP endpoint. | [19.21](/rulebook#19.21), [19.22](/rulebook#19.22), [20.5](/rulebook#20.5), [20.7](/rulebook#20.7), [20.8](/rulebook#20.8), [20.9](/rulebook#20.9), [20.10](/rulebook#20.10), [20.12](/rulebook#20.12), [20.13](/rulebook#20.13), [20.14](/rulebook#20.14), [20.16](/rulebook#20.16), [20.17](/rulebook#20.17), [20.19](/rulebook#20.19), [20.20](/rulebook#20.20), [20.21](/rulebook#20.21), [20.22](/rulebook#20.22), [20.23](/rulebook#20.23), [36.7](/rulebook#36.7), [16.78](/rulebook#16.78) |
 
 ## Taught in
 
@@ -8799,7 +8887,7 @@ Generated surfaces: what is written in place rather than imported.
 
 | Name | Signature | Meaning | Rules |
 | --- | --- | --- | --- |
-| `ParamsOf<P>` | `& { [K in RequiredNames<P>]: string \| number } & { [K in OptionalNames<P>]?: string \| number } & { [K in RestNames<P>]?: string \| number \| (string \| number)[] }` | What a route literal's segments accept. | [30.3](/rulebook#30.3), [30.4](/rulebook#30.4), [30.5](/rulebook#30.5) |
+| `ParamsOf<P>` | `& { [K in RequiredNames<P>]: string \| number } & { [K in OptionalNames<P>]?: string \| number } & { [K in RestNames<P>]?: string \| number \| (string \| number)[] }` | What a route literal's segments accept, narrowed where `abide check` declares a matcher's literals. | [30.3](/rulebook#30.3), [30.4](/rulebook#30.4), [30.5](/rulebook#30.5) |
 
 ## Taught in
 
@@ -8817,7 +8905,7 @@ Generated surfaces: what is written in place rather than imported.
 
 | Name | Signature | Meaning | Rules |
 | --- | --- | --- | --- |
-| `RouteParams<P>` | `{ [K in RequiredNames<P>]: string } & { [K in OptionalNames<P>]?: string } & { [K in RestNames<P>]: string[] }` | What a page filed under `P` reads its params as. | [23.9](/rulebook#23.9) |
+| `RouteParams<P>` | `{ [K in RequiredNames<P>]: string } & { [K in OptionalNames<P>]?: string } & { [K in RestNames<P>]: string[] }` | What a page filed under `P` reads its params as, narrowed where `abide check` declares a matcher's literals. | [23.9](/rulebook#23.9) |
 
 ## Taught in
 
@@ -9046,9 +9134,10 @@ Pages and routing: what is written in place rather than imported.
 | --- | --- | --- |
 | `<head>` | A page's, layout's or component's contribution to the document head. | [39.1](/rulebook#39.1), [39.2](/rulebook#39.2), [39.3](/rulebook#39.3), [39.4](/rulebook#39.4), [39.5](/rulebook#39.5), [39.6](/rulebook#39.6), [39.11](/rulebook#39.11), [39.12](/rulebook#39.12), [39.13](/rulebook#39.13), [39.14](/rulebook#39.14), [39.15](/rulebook#39.15), [39.16](/rulebook#39.16), [39.17](/rulebook#39.17) |
 | `view-transition-name` | What turns view transitions on, in the app's own stylesheet. | [39.7](/rulebook#39.7), [39.8](/rulebook#39.8), [39.9](/rulebook#39.9), [39.10](/rulebook#39.10), [39.18](/rulebook#39.18), [39.19](/rulebook#39.19) |
-| `[name]` | A required dynamic segment. | [16.65](/rulebook#16.65), [23.5](/rulebook#23.5), [30.3](/rulebook#30.3) |
-| `[[name]]` | An optional segment. | [23.5](/rulebook#23.5), [30.4](/rulebook#30.4) |
-| `[...name]` | A rest segment, terminal. | [23.5](/rulebook#23.5), [30.5](/rulebook#30.5) |
+| `[name]` | A required dynamic segment. | [16.65](/rulebook#16.65), [23.5](/rulebook#23.5), [30.3](/rulebook#30.3), [30.34](/rulebook#30.34), [30.36](/rulebook#30.36) |
+| `[[name]]` | An optional segment. | [23.5](/rulebook#23.5), [30.4](/rulebook#30.4), [30.34](/rulebook#30.34), [30.36](/rulebook#30.36) |
+| `[...name]` | A rest segment, terminal. | [23.5](/rulebook#23.5), [30.5](/rulebook#30.5), [30.34](/rulebook#30.34), [30.36](/rulebook#30.36) |
+| `[name=NAME]` · `[[name=NAME]]` · `[...name=NAME]` | A dynamic segment a param file's matcher decides. | [19.1](/rulebook#19.1), [23.26](/rulebook#23.26), [23.27](/rulebook#23.27), [30.19](/rulebook#30.19), [30.35](/rulebook#30.35), [30.36](/rulebook#30.36), [30.37](/rulebook#30.37) |
 | `/__abide/**` | Every endpoint abide controls. | [20.8](/rulebook#20.8) |
 
 ## Sinks
@@ -9150,9 +9239,10 @@ Configuration: what is written in place rather than imported.
 | `src/public/robots.txt` | The file answered at `/robots.txt`. | [36.11](/rulebook#36.11) |
 | `src/public/icon.png` · `src/public/icon.icns` | The files answered at `/icon.png` and `/icon.icns`, and the desktop app's icon. | [36.11](/rulebook#36.11), [38.79](/rulebook#38.79), [45.15](/rulebook#45.15) |
 | `src/**/` | A directory of the app's, a segment of the route of every file directly in it. | [23.14](/rulebook#23.14), [23.17](/rulebook#23.17), [23.22](/rulebook#23.22) |
-| `**/index.abide` | The page at its directory's route. | [19.1](/rulebook#19.1), [23.3](/rulebook#23.3), [23.4](/rulebook#23.4), [23.14](/rulebook#23.14), [23.18](/rulebook#23.18) |
-| `**/<name>.abide` | The page at its directory's route and then `<name>`. | [19.1](/rulebook#19.1), [23.3](/rulebook#23.3), [23.4](/rulebook#23.4), [23.14](/rulebook#23.14), [23.21](/rulebook#23.21) |
-| `**/<name>.ts` | A handler file: the handler its default export declares, at its directory's route and then `<name>`. | [16.2](/rulebook#16.2), [16.28](/rulebook#16.28), [16.73](/rulebook#16.73), [16.74](/rulebook#16.74), [19.1](/rulebook#19.1), [23.14](/rulebook#23.14), [23.22](/rulebook#23.22) |
+| `**/index.abide` | The page at its directory's route. | [19.1](/rulebook#19.1), [23.3](/rulebook#23.3), [23.4](/rulebook#23.4), [23.14](/rulebook#23.14), [23.18](/rulebook#23.18), [35.19](/rulebook#35.19) |
+| `**/<name>.abide` | The page at its directory's route and then `<name>`. | [19.1](/rulebook#19.1), [23.3](/rulebook#23.3), [23.4](/rulebook#23.4), [23.14](/rulebook#23.14), [23.21](/rulebook#23.21), [35.19](/rulebook#35.19) |
+| `**/<NAME>.param.ts` | A param file: the matcher a segment naming `NAME` matches by. | [23.22](/rulebook#23.22), [23.24](/rulebook#23.24), [23.25](/rulebook#23.25), [23.26](/rulebook#23.26) |
+| `**/<name>.handler.ts` | A handler file: the handler its default export declares, at its directory's route and then `<name>`. | [16.2](/rulebook#16.2), [16.28](/rulebook#16.28), [16.73](/rulebook#16.73), [16.74](/rulebook#16.74), [19.1](/rulebook#19.1), [23.14](/rulebook#23.14), [23.22](/rulebook#23.22) |
 | `**/layout.abide` | A layout, rendering every page below its route through a slot, and the hooks over that route. | [35.1](/rulebook#35.1), [35.12](/rulebook#35.12), [35.13](/rulebook#35.13), [37.2](/rulebook#37.2), [41.11](/rulebook#41.11), [41.19](/rulebook#41.19), [41.23](/rulebook#41.23) |
 | `src/launcher.abide` | The desktop launcher, beside the root layout: the `onLauncher` it calls, and its page in place of the launcher's own where it has markup. | [38.80](/rulebook#38.80), [38.82](/rulebook#38.82), [38.84](/rulebook#38.84), [38.85](/rulebook#38.85), [38.107](/rulebook#38.107) |
 | `src/layout.abide` | The root layout, whose `<script server>` is the app's own, and whose `<html>` is the document its pages are served in. | [35.15](/rulebook#35.15), [35.16](/rulebook#35.16), [35.17](/rulebook#35.17), [37.1](/rulebook#37.1), [37.3](/rulebook#37.3), [39.4](/rulebook#39.4) |
@@ -10414,7 +10504,7 @@ CLI: what is written in place rather than imported.
 | `abide scaffold <name>` | Writes a starter project. | [38.1](/rulebook#38.1), [38.42](/rulebook#38.42), [38.103](/rulebook#38.103), [38.104](/rulebook#38.104), [38.106](/rulebook#38.106), [38.112](/rulebook#38.112), [38.122](/rulebook#38.122), [38.124](/rulebook#38.124) |
 | `abide run <file> [args…]` | Runs a script under the abide runtime. | [38.2](/rulebook#38.2), [38.57](/rulebook#38.57) |
 | `abide check [dir…]` | The type-checker over a `.abide` tree. | [38.3](/rulebook#38.3), [38.31](/rulebook#38.31), [38.32](/rulebook#38.32), [38.33](/rulebook#38.33), [38.40](/rulebook#38.40), [38.105](/rulebook#38.105), [38.123](/rulebook#38.123) |
-| `abide routes [--json]` | Every address the app answers, the file answering it, and where each hook is filed. | [38.108](/rulebook#38.108), [38.123](/rulebook#38.123) |
+| `abide routes [--json]` | Every address the app answers, the file answering it, what each matcher takes, and where each hook is filed. | [38.108](/rulebook#38.108), [38.123](/rulebook#38.123) |
 | `abide dev [--port <n>]` | Watches the project and keeps the app up. | [16.23](/rulebook#16.23), [16.56](/rulebook#16.56), [37.8](/rulebook#37.8), [37.9](/rulebook#37.9), [38.4](/rulebook#38.4), [38.14](/rulebook#38.14), [38.15](/rulebook#38.15), [38.16](/rulebook#38.16), [38.17](/rulebook#38.17), [38.19](/rulebook#38.19), [38.24](/rulebook#38.24), [38.25](/rulebook#38.25), [38.26](/rulebook#38.26), [38.28](/rulebook#38.28), [38.30](/rulebook#38.30), [38.35](/rulebook#38.35), [38.36](/rulebook#38.36), [38.37](/rulebook#38.37), [38.38](/rulebook#38.38), [38.41](/rulebook#38.41), [38.43](/rulebook#38.43), [38.58](/rulebook#38.58), [38.63](/rulebook#38.63), [38.64](/rulebook#38.64), [38.65](/rulebook#38.65), [38.94](/rulebook#38.94), [38.96](/rulebook#38.96), [38.97](/rulebook#38.97), [38.123](/rulebook#38.123) |
 | `abide build` | Builds the client into content-hashed chunks and a manifest. | [38.43](/rulebook#38.43), [38.5](/rulebook#38.5), [38.18](/rulebook#38.18), [38.25](/rulebook#38.25), [38.26](/rulebook#38.26), [38.27](/rulebook#38.27), [38.30](/rulebook#38.30), [38.66](/rulebook#38.66), [38.94](/rulebook#38.94), [38.123](/rulebook#38.123) |
 | `abide start [--port <n>]` | Boots the built app. | [37.8](/rulebook#37.8), [37.10](/rulebook#37.10), [37.11](/rulebook#37.11), [37.12](/rulebook#37.12), [38.6](/rulebook#38.6), [38.100](/rulebook#38.100), [38.20](/rulebook#38.20), [38.21](/rulebook#38.21), [38.22](/rulebook#38.22), [38.23](/rulebook#38.23), [38.25](/rulebook#38.25), [38.26](/rulebook#38.26), [38.27](/rulebook#38.27), [38.28](/rulebook#38.28), [38.29](/rulebook#38.29), [38.58](/rulebook#38.58), [38.67](/rulebook#38.67), [38.68](/rulebook#38.68), [38.95](/rulebook#38.95), [38.97](/rulebook#38.97), [38.110](/rulebook#38.110), [38.123](/rulebook#38.123) |