@orkestrel/scaffold 0.0.138 → 0.0.140

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (34) hide show
  1. package/dist/agents/skills/orkestrel-parallel/scripts/lane.js +489 -23
  2. package/dist/bin/main.js +89 -29
  3. package/dist/bin/main.js.map +1 -1
  4. package/dist/host/agents/skills/orkestrel-parallel/SKILL.md +1 -1
  5. package/dist/host/agents/skills/orkestrel-parallel/scripts/lane.ts +628 -41
  6. package/dist/host/claude/agents/orkestrel.md +52 -52
  7. package/dist/host/guides/abort.md +2 -0
  8. package/dist/host/guides/browser.md +1 -1
  9. package/dist/host/guides/contract.md +314 -210
  10. package/dist/host/guides/guide.md +10 -2
  11. package/dist/host/guides/mcp.md +9 -9
  12. package/dist/host/guides/middleware.md +474 -259
  13. package/dist/host/guides/probe.md +1 -2
  14. package/dist/host/guides/router.md +282 -165
  15. package/dist/host/guides/scaffold.md +27 -18
  16. package/dist/host/guides/server.md +419 -183
  17. package/dist/host/manifest.json +14 -14
  18. package/dist/host/scripts/browsers.sh +0 -0
  19. package/dist/host/scripts/codex.sh +0 -0
  20. package/dist/host/scripts/cursor.sh +0 -0
  21. package/dist/host/scripts/deps.sh +0 -0
  22. package/dist/host/scripts/npm.sh +0 -0
  23. package/dist/host/scripts/ollama.sh +0 -0
  24. package/dist/src/core/index.cjs +17 -17
  25. package/dist/src/core/index.cjs.map +1 -1
  26. package/dist/src/core/index.js +17 -17
  27. package/dist/src/core/index.js.map +1 -1
  28. package/dist/src/server/index.cjs +6 -24
  29. package/dist/src/server/index.cjs.map +1 -1
  30. package/dist/src/server/index.d.cts +1 -1
  31. package/dist/src/server/index.d.ts +1 -1
  32. package/dist/src/server/index.js +7 -25
  33. package/dist/src/server/index.js.map +1 -1
  34. package/package.json +14 -14
@@ -42,7 +42,7 @@ const response = await dispatcher.handle(new Request('http://x/users/7'), { user
42
42
 
43
43
  Path patterns are `/`-prefixed: a literal segment (`/users`), a `:name` param
44
44
  (one segment), or a final `*name` wildcard (captures the rest of the path).
45
- Matching is case-sensitive by default (`sensitive: false` opts out); a single
45
+ Matching is case-sensitive by default (`sensitive: false` folds ASCII letters); a single
46
46
  trailing slash is always optional except on the root `/` and the empty
47
47
  pattern.
48
48
 
@@ -58,34 +58,46 @@ Browser and server usage appear under [Patterns](#patterns).
58
58
 
59
59
  ### Constants
60
60
 
61
- | Name | Kind | Signature | Summary |
62
- | --------------- | ----- | ----------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
63
- | `METHOD_LIST` | const | `readonly ["GET", "POST", "PUT", "PATCH", "DELETE", "HEAD", "OPTIONS"]` | Lists the HTTP methods a `DispatcherInterface` registers routes under, in canonical order — a frozen literal tuple, and the single source the `Method` type, `HTTP_METHODS`, and `parseMethod` are all derived from. |
64
- | `HTTP_METHODS` | const | `ReadonlySet<string>` | Holds every HTTP method a `DispatcherInterface` registers routes under as a `ReadonlySet` — backs the registration guard (`add` rejects any `method` outside this set). |
65
- | `TIER_LITERAL` | const | `2` | Names the specificity tier for a \*\*literal\*\* path segment (`/users`) — the highest tier, always outranking a param or wildcard segment at the same position. |
66
- | `TIER_PARAM` | const | `1` | Names the specificity tier for a \*\*param\*\* path segment (`:name`) — ranks below a literal segment and above a wildcard segment at the same position. |
67
- | `TIER_WILDCARD` | const | `0` | Names the specificity tier for a \*\*wildcard\*\* path segment (`*name`) — the lowest tier; a wildcard only ever wins against another wildcard shape (an equal-specificity tie resolved by registration order). |
61
+ | Name | Kind | Signature | Summary |
62
+ | --------------------- | ----- | ----------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
63
+ | `METHOD_LIST` | const | `readonly ["GET", "POST", "PUT", "PATCH", "DELETE", "HEAD", "OPTIONS"]` | Lists the HTTP methods a `DispatcherInterface` registers routes under, in canonical order — a frozen literal tuple, and the single source the `Method` type, `HTTP_METHODS`, and `parseMethod` are all derived from. |
64
+ | `HTTP_METHODS` | const | `ReadonlySet<string>` | Holds every HTTP method a `DispatcherInterface` registers routes under as a `ReadonlySet` — backs the registration guard (`add` rejects any `method` outside this set). |
65
+ | `PATH_ENCODE_SET` | const | `ReadonlySet<string>` | Holds the printable ASCII members of the path encode set `encodePath` reads: the URL Standard's path percent-encode set plus `\|`, beside every C0 control, U+007F, and greater code point. |
66
+ | `PATH_ESCAPE_PATTERN` | const | `RegExp` | Matches each ASCII code point `encodePath` writes as one escape — a C0 control, a member of `PATH_ENCODE_SET`, or U+007F — in one global `replace` pass. |
67
+ | `PATH_WIDE_PATTERN` | const | `RegExp` | Matches each run of non-ASCII code points `encodePath` hands to one `encodeURIComponent` call, in one global `replace` pass. |
68
+ | `PERCENT_ESCAPES` | const | `readonly string[]` | Lists the uppercase percent-escape of every byte value, indexed by the byte, so `encodePath` writes each escape with one lookup. |
69
+ | `PATH_ENCODE_PATTERN` | const | `RegExp` | Matches one code point `encodePath` writes as escapes: a C0 control, a member of `PATH_ENCODE_SET`, U+007F, or any greater code point. |
70
+ | `PATH_REFUSED_SET` | const | `ReadonlySet<string>` | Holds the code points a route pattern must not hold: `\`, tab, line feed, and carriage return, which a URL parser reads as a separator or deletes, so the pattern would name a path other than its text. |
71
+ | `PROTOTYPE_KEYS` | const | `ReadonlySet<string>` | Holds the own property names of `Object.prototype` — the names `compilePath` refuses as a param name, so a params record never shadows or drops an inherited key. |
72
+ | `TIER_LITERAL` | const | `2` | Names the specificity tier for a \*\*literal\*\* path segment (`/users`) — the highest tier, always outranking a param or wildcard segment at the same position. |
73
+ | `TIER_PARAM` | const | `1` | Names the specificity tier for a \*\*param\*\* path segment (`:name`) — ranks below a literal segment and above a wildcard segment at the same position. |
74
+ | `TIER_WILDCARD` | const | `0` | Names the specificity tier for a \*\*wildcard\*\* path segment (`*name`) — the lowest tier; a wildcard only ever wins against another wildcard shape (an equal-specificity tie resolved by registration order). |
68
75
 
69
76
  ### Helpers
70
77
 
71
78
  | Name | Kind | Signature | Summary |
72
79
  | ---------------------- | -------- | -------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
73
- | `canonicalizePath` | function | `(path: string) => string` | Canonicalizes a route path for registry identity — strips a single trailing slash, except the root `/` (and the empty pattern). The trailing-slash fold `compilePath` normalizes a pattern through, so identity agrees with the matcher. |
80
+ | `canonicalizePath` | function | `(path: string) => string` | Canonicalizes a route path for registry identity — encodes it with `encodePath` and strips a single trailing slash, except the root `/` (and the empty pattern). The trailing-slash fold `compilePath` normalizes a pattern through, so identity agrees with the matcher. |
74
81
  | `computeDispatchKey` | function | `(entry: RouteEntry<{ readonly method: Method; }>) => string` | Computes the canonical `METHOD /path` registry key for a method-dimensioned dispatcher route. |
75
- | `compilePath` | function | `(path: string, sensitive?: boolean) => CompiledPath` | Compiles a route path pattern into an anchored regex and its ordered param names. |
82
+ | `compilePath` | function | `(path: string, sensitive?: boolean) => CompiledPath` | Compiles a route path pattern into an anchored regex, its ordered param names, and its specificity vector. |
83
+ | `encodePath` | function | `(text: string) => string` | Encodes path text, raw or already encoded, into the canonical form the router compares: each member of its path encode set becomes its UTF-8 percent-escapes. |
84
+ | `collectInputs` | function | `<T>(input: T \| readonly T[]) => readonly T[]` | Returns the input list as it is, or a one-entry list holding a single input — the shape every batch-capable `add` reads. |
76
85
  | `decodeParam` | function | `(value: string) => string` | Decodes one captured param value from a URL, tolerating a malformed percent-escape — the decode `matchPath` applies to each captured group. |
77
86
  | `matchPath` | function | `(compiled: CompiledPath, pathname: string) => Readonly<Record<string, string>> \| undefined` | Extracts the URL-decoded params a compiled path captures from a concrete pathname, or `undefined` when the pathname does not match. |
78
87
  | `classifySegment` | function | `(segment: string, isFinal: boolean) => number` | Classifies one path segment into its specificity tier — the same syntax `compilePath` rewrites: a syntactically valid `:name` head is a param segment, a final `*name` is a wildcard segment, and everything else (including a literal segment that merely contains a `:` mid-string, for example `a:b`) is a literal segment. |
79
- | `computeSpecificity` | function | `(path: string) => readonly number[]` | Computes a route path's specificity vector — the per-segment type ranking that breaks a tie when several registered routes match the same concrete pathname. |
80
- | `compareSpecificity` | function | `(a: string, b: string) => number` | Compares two route paths by specificity — the comparator that picks the most-specific matching route (literal-over-param-over-wildcard, registration-order-independent). |
88
+ | `computeSpecificity` | function | `(path: string) => readonly SegmentRank[]` | Computes a route path's specificity vector — one `SegmentRank` per segment, the ranking that picks the winner when several registered routes match the same concrete pathname. |
89
+ | `compareSpecificity` | function | `(a: readonly SegmentRank[], b: readonly SegmentRank[]) => number` | Compares two specificity vectors — the comparator that picks the most-specific matching route: tier first, then literal length, segment by segment. |
81
90
  | `joinPaths` | function | `(prefix: string, path: string) => string` | Joins a group prefix and a route path into one `/`-prefixed path, normalizing duplicate or missing joining slashes. |
82
91
  | `defineRoute` | function | `<const Path extends string, TState = undefined>(input: RouteInput<Path, TState>) => RouteInput<Path, TState>` | Provides an identity pass-through for a `RouteInput` that pins its `Path` generic to the literal registration-site string, so `context.params` types correctly through `PathParams` without an explicit type argument. |
83
92
  | `computeNavigationKey` | function | `(entry: RouteEntry<unknown>) => string` | Computes the canonical path key a `Navigator` registers a browser navigation route under. |
84
93
  | `extractHashPath` | function | `(hash: string) => string` | Extracts the `/`-prefixed pathname from a `location.hash` value — strips the leading `#` (keeping the route's own leading `/`) and any `?query` suffix. |
85
- | `resolveLocationPath` | function | `(location: Pick<Location, 'hash' \| 'pathname'>, history: boolean, base?: string) => string` | Resolves the `/`-prefixed pathname to match for the current location, in either navigation mode — the one seam `extractHashPath` (hash mode) and history-mode base-stripping share. |
94
+ | `resolveLocationPath` | function | `(location: Pick<Location, 'hash' \| 'pathname'>, history: boolean, base?: string) => string \| undefined` | Resolves the `/`-prefixed pathname to match for the current location, in either navigation mode — the one seam `extractHashPath` (hash mode) and history-mode base-stripping share. |
86
95
  | `findAnchor` | function | `(event: Event) => HTMLAnchorElement \| undefined` | Finds the nearest enclosing `<a>` element a DOM event originated from, by walking its composed path — the pure lookup behind history-mode link interception. |
87
96
  | `buildRequest` | function | `(message: IncomingMessage, options?: RequestOptions) => Request` | Builds a fetch-standard `Request` from a `node:http` `IncomingMessage` — the server-adapter half of the fetch/node conversion seam. |
88
97
  | `sendResponse` | function | `(response: Response, target: ServerResponse) => Promise<void>` | Writes a fetch-standard `Response` back to a `node:http` `ServerResponse` — the reverse half of the fetch/node conversion seam. |
98
+ | `buildURL` | function | `(message: IncomingMessage, origin?: string) => URL` | Builds the URL of a `node:http` request from its request target, by the target's form. |
99
+ | `readChunk` | function | `(message: IncomingMessage, signal: AbortSignal) => Promise<Uint8Array \| undefined>` | Reads the next chunk of a `node:http` request body, waiting for one to arrive. |
100
+ | `discardBody` | function | `(message: IncomingMessage, discard: AbortController) => void` | Discards the unread rest of a `node:http` request body in place, leaving the connection reusable. |
89
101
 
90
102
  ### Parsers
91
103
 
@@ -98,19 +110,13 @@ Browser and server usage appear under [Patterns](#patterns).
98
110
  | Name | Kind | Signature | Summary |
99
111
  | ------------------- | -------- | -------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
100
112
  | `isEncryptedSocket` | function | `(socket: unknown) => socket is { readonly encrypted: true; }` | Determines whether a `node:http` connection socket is TLS-encrypted — the total, never-throwing narrow `buildRequest` uses to pick the derived scheme (`https` vs `http`). |
101
-
102
- ### Handlers
103
-
104
- | Name | Kind | Signature | Summary |
105
- | ----------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
106
- | `handleListenerRequest` | function | `<TState>(dispatcher: DispatcherInterface<TState>, state: StateFunction<TState>, request: IncomingMessage, response: ServerResponse) => Promise<void>` | Handles one `node:http` request through a core dispatcher and writes its fetch-standard response. |
107
- | `createListener` | function | `<TState>(dispatcher: DispatcherInterface<TState>, state: StateFunction<TState>) => ListenerFunction` | Creates a `node:http` request listener over a core `DispatcherInterface` — the whole server face's entry point: converts the incoming message to a fetch `Request`, hands it to the dispatcher with the consumer's per-request `state`, and writes the resulting `Response` back. |
113
+ | `isAuthority` | function | `(value: unknown) => value is string` | Checks whether a value is an HTTP authority a server accepts: a host with an optional port, and no userinfo. |
108
114
 
109
115
  ### Classes
110
116
 
111
117
  | Name | Kind | Signature | Summary |
112
118
  | --------------- | ----- | ----------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
113
- | `Router` | class | `new <Meta>(options?: RouterOptions<Meta>) => RouterInterface<Meta>` | Represents the path-matching + registry engine — registers `{ path, meta, name? }` entries (compiling each path once) and resolves a concrete pathname to the most specific matching entry. The shared machine both the `Navigator` (browser) and the `Dispatcher` (core, method-dimensioned) compose. |
119
+ | `Router` | class | `new <Meta>(options?: RouterOptions<Meta>) => RouterInterface<Meta>` | Represents the path-matching + registry engine — registers `{ path, meta, name? }` entries (compiling each path once) and resolves raw or encoded text to the most specific matching entry. The shared machine both the `Navigator` (browser) and the `Dispatcher` (core, method-dimensioned) compose. |
114
120
  | `Group` | class | `new <Meta>(parent: RouterInterface<Meta>, prefix: string) => GroupInterface<Meta>` | Represents a prefix-scoped registration handle over a `Router` — pure string composition, no independent state or storage. |
115
121
  | `Dispatcher` | class | `new <TState = undefined>(options?: DispatcherOptions<TState>) => DispatcherInterface<TState>` | Represents the fetch-standard, method-dimensioned dispatch entity — layers HTTP method dispatch and web-standard `Request`/`Response` handling over one internal `Router<RouteRecord<TState>>`. The core machine the server face and any fetch-native runtime consume directly. |
116
122
  | `DispatchGroup` | class | `new <TState>(parent: DispatcherInterface<TState>, prefix: string) => DispatchGroupInterface<TState>` | Represents a prefix-scoped registration handle over a `Dispatcher` — the method-dimensioned counterpart of `Group`. |
@@ -127,12 +133,13 @@ Browser and server usage appear under [Patterns](#patterns).
127
133
  | `TakeIdentifierTail` | type | ``S extends `${infer Head}${infer Tail}` ? Head extends IdentifierChar ? TakeIdentifierTail<Tail, `${Acc}${Head}`> : Acc : Acc`` | Consumes the identifier-continuation run at the front of a string literal, char by char, appending each onto the accumulator. |
128
134
  | `IdentifierHead` | type | ``S extends `${infer Head}${infer Tail}` ? Head extends IdentifierStartChar ? TakeIdentifierTail<Tail, Head> : '' : ''`` | Captures the identifier at the front of a string literal, or an empty string when the literal does not begin with an identifier-start char. |
129
135
  | `SegmentParam` | type | ``Segment extends `:${infer Rest}` ? IdentifierHead<Rest> extends infer Name extends string ? Name extends '' ? unknown : { readonly [K in Name]: string; } : unknown : Segment extends `*${infer Rest}` ? IdentifierHead<Rest> extends infer Name extends string ? Name extends '' ? unknown : { readonly [K in Name]: string; } : unknown : unknown`` | Contributes one path segment's type-level param record — the type-level mirror of the runtime `classifySegment` and `compilePath` segment parser. |
130
- | `CompiledPath` | interface | `{ regex, params }` | Represents a compiled route path — the anchored regex plus its ordered param names. |
136
+ | `SegmentRank` | interface | `{ tier, length }` | Represents one segment's place in a route path's specificity vector — its tier, then the length of the literal text it carries. |
137
+ | `CompiledPath` | interface | `{ regex, params, specificity }` | Represents a compiled route path — the anchored regex, its ordered param names, and its specificity vector. |
131
138
  | `RouteEntry` | interface | `{ path, meta, name? }` | Represents one registered route in a `RouterInterface` — the `path` pattern plus the opaque `meta` payload to return on a match, with an optional `name`. |
132
139
  | `RouterMatch` | interface | `{ path, params, meta, name? }` | Represents one matched route — the winning entry's registered pattern, its decoded params, its `meta` payload, and its optional `name`. |
133
140
  | `AnswerHandler` | type | `(meta: Meta) => boolean` | Represents the native-override seam — a predicate deciding whether an entry's `meta` answers a given `match` call, beyond path matching. |
134
141
  | `RouterOptions` | interface | `{ entries?, sensitive?, key? }` | Represents the options for `createRouter` — an optional initial entry set, the case-sensitivity toggle, and the dedup identity function. |
135
- | `RouterInterface` | interface | `{ count, add(), match(), entries(), group(), clear() }` | Represents the path-matching + registry engine contract (the behavioral-interface role for the one-class-per-file `Router`). Registers `{ path, meta, name? }` entries (compiling each path once) and resolves a concrete pathname to the most specific matching entry — a literal segment beats a param beats a wildcard at the earliest differing segment, registration-order-independent. The shared engine both the `Navigator` (browser) and the `Dispatcher` (core, method-dimensioned) compose. |
142
+ | `RouterInterface` | interface | `{ count, add(), match(), entries(), group(), clear() }` | Represents the path-matching + registry engine contract (the behavioral-interface role for the one-class-per-file `Router`). Registers `{ path, meta, name? }` entries (compiling each path once) and resolves path text, raw or encoded, to the most specific matching entry by the per-segment precedence `compareSpecificity` defines, a remaining tie going to the earlier registration. The shared engine both the `Navigator` (browser) and the `Dispatcher` (core, method-dimensioned) compose. |
136
143
  | `GroupInterface` | interface | `{ prefix, add(), group() }` | Represents a prefix-scoped registration handle over a `RouterInterface` — pure string composition, no independent state or storage. |
137
144
  | `Method` | type | `(typeof METHOD_LIST)[number]` | Names the HTTP methods a `DispatcherInterface` dimensions dispatch over — derived from `METHOD_LIST`, whose membership counterpart is `HTTP_METHODS`. |
138
145
  | `RouteContext` | interface | `{ params, pattern, url, state }` | Represents the ambient context a `RouteHandler` receives alongside the raw `Request` — decoded params, the winning pattern, the parsed URL, and the consumer's opaque per-request state. |
@@ -146,10 +153,8 @@ Browser and server usage appear under [Patterns](#patterns).
146
153
  | `DispatchGroupInterface` | interface | `{ prefix, add(), group() }` | Represents a prefix-scoped registration handle over a `DispatcherInterface` — the method-dimensioned counterpart of `GroupInterface`. |
147
154
  | `NavigatorEventMap` | type | `{ readonly navigate: readonly [match: RouterMatch<Meta>]; }` | Represents the `Navigator`'s event map — the single `navigate` signal a consumer observes. |
148
155
  | `NavigatorOptions` | interface | `{ routes, history?, base?, fallback?, guard?, intercept?, sensitive?, on?, error? }` | Represents the options for `createNavigator` — the `routes` to dispatch between, the navigation substrate, the optional guard hook, and the Emitter pattern's wiring. |
149
- | `NavigatorInterface` | interface | `{ router, emitter, active, start(), stop(), navigate(), match(), destroy() }` | Represents the headless History/hash navigation entity contract (the behavioral-interface role for the one-class-per-file `Navigator`). Composes a core `Router<Meta>`, resolves the current location on `start()` and on every subsequent navigation event, tracks `active`, and emits `navigate` through the `EmitterInterface`. |
150
- | `RequestOptions` | interface | `{ origin?, response? }` | Represents the options for `buildRequest` — URL origin and response-side disconnect tracking. |
151
- | `ListenerFunction` | type | `(request: IncomingMessage, response: ServerResponse) => void` | Represents a `node:http` request handler — the function `createListener` returns, matching `http.createServer`'s handler signature. |
152
- | `StateFunction` | type | `(message: IncomingMessage) => TState` | Derives a consumer's opaque per-request `TState` from the raw `IncomingMessage` — the `state` argument `createListener` threads into `dispatcher.handle`. |
156
+ | `NavigatorInterface` | interface | `{ router, emitter, active, start(), stop(), navigate(), destroy() }` | Represents the headless History/hash navigation entity contract (the behavioral-interface role for the one-class-per-file `Navigator`). Composes a core `Router<Meta>`, resolves the current location on `start()` and on every subsequent navigation event, tracks `active`, and emits `navigate` through the `EmitterInterface`. |
157
+ | `RequestOptions` | interface | `{ origin?, response?, signal? }` | Represents the options for `buildRequest` — URL origin, response-side disconnect tracking, and a linked cancellation signal. |
153
158
 
154
159
  The `count` member of `RouterInterface`, the `prefix` member of `GroupInterface` and
155
160
  `DispatchGroupInterface`, the `router` and `emitter` members of `DispatcherInterface`, and the
@@ -197,13 +202,12 @@ declaration it belongs to:
197
202
  The navigation entity's call-signature members, each documented on the interface
198
203
  declaration it belongs to:
199
204
 
200
- | Method | Returns | Summary |
201
- | ---------- | -------------------------- | ---------------------------------------------------------------------------------------------------------------------------- |
202
- | `start` | `void` | Begins listening and resolves the current location — idempotent, so a second call is a no-op. |
203
- | `stop` | `void` | Stops listening and aborts any pending guard — idempotent. |
204
- | `navigate` | `void` | Navigates programmatically — sets `location.hash` in hash mode or calls `history.pushState` in history mode, then resolves. |
205
- | `match` | `RouterMatch \| undefined` | Looks one path up through the underlying `Router` — a pure lookup with no location read, no fallback, no guard, and no emit. |
206
- | `destroy` | `void` | Stops listening and tears down the emitter. |
205
+ | Method | Returns | Summary |
206
+ | ---------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |
207
+ | `start` | `void` | Begins listening and resolves the current location — idempotent, so a second call is a no-op. |
208
+ | `stop` | `void` | Stops listening and aborts any pending guard — idempotent. |
209
+ | `navigate` | `void` | Navigates programmatically — runs the guard, then pushes the entry (`#path` in hash mode, the `base`-joined path in history mode) and commits. |
210
+ | `destroy` | `void` | Stops listening, aborts any pending guard, and tears down the emitter. |
207
211
 
208
212
  #### `GroupInterface`
209
213
 
@@ -240,41 +244,81 @@ These invariants hold across `src/core` / `src/browser` / `src/server` ↔
240
244
  exhaustive, both directions — and `Router` / `Group` / `Dispatcher` /
241
245
  `DispatchGroup` / `Navigator` expose the same public methods, no more.
242
246
  3. **Path grammar.** Segment kinds: literal (`/users`), param
243
- (`:name`, one segment), wildcard (`*name`, final segment only, captures
244
- the rest of the path including slashes). A wildcard anywhere but the
245
- final segment throws a `ContractError` at compile time, guarded at the boundary.
246
- 4. **Precedence tiers.** A literal segment (`TIER_LITERAL`, 2) outranks a
247
+ (`:name`, one segment, with optional literal text after the name, as in
248
+ `:name.json`), wildcard (`*name`, final segment only, captures the rest of
249
+ the path including slashes). `compilePath` throws a `ContractError` at
250
+ registration for a wildcard anywhere but the final segment, a final
251
+ `*name` followed by more text (`/files/*rest.json`), a param or wildcard
252
+ named for a `PROTOTYPE_KEYS` member (`:__proto__`, `:constructor`), and a
253
+ name used twice (`/a/:id/b/:id`). It also throws, with code `pattern`, for
254
+ a pattern holding `\`, tab, line feed, or carriage return anywhere, because
255
+ a URL parser reads `\` as a separator and deletes the others; the `limit`
256
+ names each one and its escape (`%5C`, `%09`, `%0A`, `%0D`). 0.0.22 refused
257
+ only the wildcard outside the final segment and registered every other
258
+ pattern this item names. The matcher
259
+ compares one canonical text, which `encodePath` writes from its own table,
260
+ `PATH_ENCODE_SET`, on both sides. The table is the URL Standard's path
261
+ percent-encode set (Last Updated 2026-11-14, snapshot `47721bbd`) plus
262
+ `|`, a declared departure: Chromium encodes `|` in a path as `%7C` and Node
263
+ leaves it raw, so with `|` in the table both compare as `%7C`. The encoder
264
+ runs on the pattern at
265
+ registration, and on the request text inside `router.match`,
266
+ `router.entries`, and `matchPath`. So `/café` matches `/café` and
267
+ `/caf%C3%A9`, `/^w` matches `/^w` and `/%5Ew`, and `router.match` takes path
268
+ text raw or encoded. Nothing is decoded before matching, so `/us%65rs`
269
+ does not match `/users`, and `/100%25` does not match `/100%`. In 0.0.22
270
+ the matcher compared the pattern as written with the text as given, so
271
+ `/café` answered 404 through `Dispatcher.handle`, whose pathname is
272
+ encoded, and `/a|b` missed `/a%7Cb`, the form Chromium writes. Each capture is decoded with
273
+ `decodeParam` and is opaque text the router refuses nothing in:
274
+ `/files/*rest` captures `../../etc/passwd` from
275
+ `/files/..%2F..%2Fetc%2Fpasswd`. A consumer that maps a capture to a file
276
+ path must contain it within its root.
277
+ 4. **Precedence.** A literal segment (`TIER_LITERAL`, 2) outranks a
247
278
  param (`TIER_PARAM`, 1), which outranks a wildcard (`TIER_WILDCARD`, 0).
248
- Two matching routes compare left to right, and the higher tier at the
249
- earliest differing segment wins, independent of registration order. A
250
- shorter pattern that is a prefix of a longer one ranks below it. An
251
- equal-specificity tie, possible only between distinct wildcard shapes,
252
- resolves to the earliest registered.
279
+ Two matching routes compare left to right, segment by segment: the higher
280
+ tier wins, and within one tier the longer literal text wins, so
281
+ `/files/:name.json` outranks `/files/:name` in either registration order.
282
+ A shorter pattern that is a prefix of a longer one ranks below it. A
283
+ remaining tie, such as `/t/:a.js` against `/t/:b.js`, goes to the earlier
284
+ registration. In 0.0.22 only the tier counted, so the earlier registration
285
+ of `/files/:name` and `/files/:name.json` won.
253
286
  5. **Trailing slash is insensitive.** A single trailing slash on the request
254
287
  path is always optional, folded both at registration (`canonicalizePath`)
255
288
  and at match time — except the root `/` and the empty pattern, which are
256
289
  exempt and anchor exactly.
257
290
  6. **Case-sensitive by default.** `sensitive: true` (`Router`/`Dispatcher`
258
- construction) is the default; `sensitive: false` folds case during
259
- matching without altering the pattern's own stored casing.
291
+ construction) is the default; `sensitive: false` folds the ASCII letters
292
+ A to Z with a to z during matching, in literal text and in escape hex,
293
+ without altering the pattern's own stored casing. No other letter folds:
294
+ `/CAFÉ` misses `/café` under either setting, while `/CAFé` and
295
+ `/caf%c3%a9` hit it under `sensitive: false`. In 0.0.22 `sensitive: false`
296
+ folded every letter the regular expression `i` flag folds, so `/CAFÉ` hit
297
+ `/café`.
260
298
  7. **Dedup with `key`.** When `RouterOptions.key` is set, an entry whose
261
299
  computed key already exists replaces the prior entry in place (last write
262
300
  wins, no engine rebuild); `Dispatcher` always constructs its internal
263
301
  `Router` with `key: computeDispatchKey`, which pairs the route's method
264
- with `canonicalizePath(entry.path)`, so two registrations differing only
265
- by a trailing slash replace each other while different methods stay
266
- distinct.
302
+ with `canonicalizePath(entry.path)`, the encoded pattern with one trailing
303
+ slash removed, so two registrations differing only by a trailing slash or
304
+ by encoding (`/café` and `/caf%C3%A9`) replace each other while different
305
+ methods stay distinct. A batch `add` admits every entry before it registers
306
+ any, so a refused batch registers nothing.
267
307
  8. **The `answers` seam.** `RouterInterface.match`'s optional
268
308
  `AnswerHandler<Meta>` predicate is the single native-override point both
269
309
  faces compose differently: the `Dispatcher` passes a method-check, the
270
310
  browser `Navigator` omits it entirely — every path match answers.
271
311
  9. **Dispatch semantics.** A `HEAD` request with no explicit `HEAD` route
272
- runs the matching `GET` handler and strips the response body. An
273
- `OPTIONS` request with no explicit `OPTIONS` route answers `204` with a
274
- derived `Allow` header (from `router.entries(pathname)`, `GET` implying
275
- `HEAD`). A path-matches-but-method-doesn't dispatch invokes the
276
- `unmethoded` responder (default `405` + `Allow`); nothing matching
277
- invokes the `unmatched` responder (default `404`). **A handler throw
312
+ runs the matching `GET` handler, cancels the `GET` response body, and
313
+ answers with its status and headers alone. An `OPTIONS` request with no
314
+ explicit `OPTIONS` route answers `204` with a derived `Allow` header: the
315
+ methods of `router.entries(pathname)` in registration order, then `HEAD`
316
+ when `GET` is present, then `OPTIONS`. A path-matches-but-method-doesn't
317
+ dispatch invokes the `unmethoded` responder with the same set (default
318
+ `405` + `Allow`, so `GET` alone reads `GET, HEAD, OPTIONS`); nothing matching
319
+ invokes the `unmatched` responder (default `404`). In 0.0.22 the `405`
320
+ `Allow` header left `OPTIONS` out, so `GET` alone read `GET, HEAD`, and
321
+ auto-`HEAD` dropped the `GET` body without cancelling it. **A handler throw
278
322
  propagates uncaught** — the dispatcher never invents an error boundary
279
323
  (that is the consuming server's policy).
280
324
  10. **Wildcard trailing-slash capture is asymmetric with param folding
@@ -302,26 +346,53 @@ These invariants hold across `src/core` / `src/browser` / `src/server` ↔
302
346
  14. **The history toggle.** `history: false` (default) reads/writes
303
347
  `location.hash` and binds `hashchange`; `history: true` reads/writes through
304
348
  `pushState`/`popstate`, with an optional `base` path prefix stripped
305
- before matching and prepended when navigating. `intercept: true`
306
- (history mode only) adds same-origin `<a>` click interception — a plain
349
+ before matching and prepended when navigating. `base` is compared in the
350
+ encoded form `location.pathname` carries, so `base: '/café'` strips from
351
+ `/caf%C3%A9/users/7`. `intercept: true` (history mode only) adds
352
+ same-origin `<a>` click interception for a link inside `base` — a plain
307
353
  left-click with no modifier keys, no `target`, and no `download`
308
- attribute.
309
- 15. **Fallback semantics.** A location that matches nothing resolves the
310
- configured `fallback` pattern (default: the first route's path) through
311
- the same engine. A `fallback` that itself matches no registered route
312
- leaves `active` `undefined` and emits nothing — no phantom match is ever
313
- fabricated.
354
+ attribute. A link outside `base` navigates natively, where 0.0.22
355
+ intercepted it and pushed it under `base`, so `/other/page` became
356
+ `/app/other/page`. In history mode, `navigate` throws a `ContractError`
357
+ coded `pattern` for a path that resolves on another origin, such as
358
+ `//elsewhere.example/b`, before the guard runs; 0.0.22 handed that path to
359
+ `pushState`, which threw a `DOMException`. `navigate` pushes an
360
+ entry in both modes, `#path` in hash mode, and writes `{ index }` into its
361
+ `history.state`; `start` writes `{ index: 0 }` to an entry that carries no
362
+ index. A hash `navigate` to the hash the location shows keeps its entry.
363
+ 15. **Fallback semantics.** A location that matches nothing, or in history
364
+ mode lies outside `base`, resolves the configured `fallback` pattern
365
+ (default: the first route's path) through the same engine. 0.0.22 matched
366
+ a location outside `base` by its whole pathname, so `/other/page` under
367
+ `base: '/app'` resolved the `/other/page` route. A `fallback`
368
+ that itself matches no registered route leaves `active` `undefined` and
369
+ emits nothing — no phantom match is ever fabricated.
314
370
  16. **Guard + supersede semantics.** An optional `guard(to, from, signal)` may
315
- veto (or asynchronously veto) a navigation. The `Navigator` mints an
316
- `@orkestrel/abort` handle per navigation and aborts the previous handle
317
- when a newer navigation starts (or on `stop`/`destroy`) — a guard verdict
318
- that resolves after its navigation was superseded (`signal.aborted`) is
319
- discarded, same as a synchronous `false`/rejected verdict: `active` stays
320
- unchanged and nothing is emitted. A guard throw routes to the `error`
321
- handler (not through the emitter's own `emit`) and vetoes.
371
+ veto (or asynchronously veto) a navigation.
372
+ - `navigate` and an intercepted link ask the guard before the URL moves: a
373
+ veto leaves the location, the history length, and `active` unchanged,
374
+ and an allowed navigation pushes its entry, then commits.
375
+ - When the browser moves the URL first (`popstate` or `hashchange`), a veto
376
+ moves it back with `history.go` to the entry `active` describes, by the
377
+ `index` both entries carry. An entry the navigator did not write — a
378
+ native fragment link, an address-bar edit, or an entry from before
379
+ `start` — carries no index: the location stays where the browser put
380
+ it, `active` stays unchanged, and the consumer reconciles them.
381
+ - Each navigation holds an `@orkestrel/abort` handle until its verdict
382
+ arrives. A newer navigation, `stop`, and `destroy` abort every pending
383
+ handle, and a verdict that resolves after its abort (`signal.aborted`)
384
+ is discarded, same as a synchronous `false`/rejected verdict: `active`
385
+ stays unchanged and nothing is emitted. A guard throw routes to the
386
+ `error` handler (not through the emitter's own `emit`) and vetoes.
387
+ - A `navigate` called from a `navigate` listener runs in a microtask after
388
+ the emission ends, unless a later navigation supersedes it first. Every
389
+ listener of one emission reads `active` equal to the match it receives,
390
+ and the second navigation's emission follows.
391
+ - After `destroy`, `start` and `navigate` do nothing: no listener, no
392
+ history entry, and no emit.
322
393
  17. **Case-sensitive by default.** `sensitive: true` (forwarded to the
323
- underlying `Router`) is the default; `sensitive: false` folds case during
324
- matching.
394
+ underlying `Router`) is the default; `sensitive: false` folds the ASCII
395
+ letters A to Z with a to z during matching, and no other letter.
325
396
  18. **Intercepted links carry pathname only (known limitation).** Click
326
397
  interception passes only the intercepted link's `/`-prefixed pathname
327
398
  through to `navigate` — a query string on the link's `href` is not
@@ -333,37 +404,56 @@ These invariants hold across `src/core` / `src/browser` / `src/server` ↔
333
404
  an `HTMLAnchorElement` — an SVG `<a>` (`SVGAElement`) is not intercepted,
334
405
  even inside a same-origin document, and falls through to the browser's
335
406
  native navigation.
336
- 20. **Signal fires on client disconnect.** `buildRequest` mints an
337
- `@orkestrel/abort` handle and builds the `Request` over its `signal`. The
338
- handle aborts if the request connection closes before the message finished
339
- (`!message.complete`), preserving that incomplete-request error, or if the
340
- paired `RequestOptions.response` closes before the response finished
341
- (`!response.writableEnded`). `handleListenerRequest` always supplies that
342
- response, so a handler observes both an incomplete request body and the
343
- ordinary post-request client disconnect through `request.signal`, with zero
344
- router-specific cancellation API. A normally completed response does not
345
- abort the signal, and each close observer is one-shot.
346
- 21. **Transport-level 500 is a last resort, not an error policy.**
347
- `createListener`'s handler wraps `dispatcher.handle` in a try/catch purely
348
- for the connection: when nothing has been sent yet, it writes a bare `500`
349
- head and ends the response (never leaking a hanging socket); after headers
350
- are already sent, it destroys the connection outright. The router still
351
- owns no error policy — a consumer wanting mapped error responses installs
352
- its own boundary around `dispatcher.handle` directly; and the core
353
- `Dispatcher` never swallows a handler throw into a generic response, as
354
- stated earlier.
355
- 22. **Streaming both ways.** `buildRequest` streams a body-carrying method's
356
- message into the `Request` through a manual `ReadableStream` pump — a `for
357
- await` loop over the `IncomingMessage` enqueueing each chunk, with
358
- `duplex: 'half'` set as Node's fetch implementation requires for a
359
- streamed request body; `sendResponse` streams a non-`null` `Response`
360
- body back to the `ServerResponse` chunk by chunk, ending the target when
361
- the stream completes. When a write reports backpressure, it waits for
362
- `drain` before pulling the next body chunk, raced against target
363
- close/error/destruction so a client disconnect stops the pump promptly;
364
- every race listener is removed when that wait settles. A target destroyed
365
- mid-stream stops cleanly without throwing.
366
- 23. **Header fidelity.** `buildRequest` copies every incoming header
407
+ 20. **The target form decides the URL.** `buildRequest` builds its URL
408
+ through `buildURL`. An origin-form target is appended to the origin, so
409
+ `GET //evil.example/admin` keeps the origin's authority and routes the
410
+ pathname `//evil.example/admin`. An absolute-form target takes its own
411
+ authority, for `http:` and `https:` only. The asterisk form and every
412
+ other form throw a `ContractError`. The origin is `RequestOptions.origin`
413
+ when given; otherwise it is the connection's scheme and the `Host` header.
414
+ A `Host` header that is present must pass `isAuthority` for every target
415
+ form, with `RequestOptions.origin` set as well: a host with an optional
416
+ port, with no path, userinfo, whitespace, or port above 65535, on one
417
+ field line only (RFC 9112 section 3.2). A consuming server maps the throw
418
+ to 400. In 0.0.22 `buildRequest` resolved the target against the origin
419
+ with no check of its form or of the `Host` header: `//evil.example/admin`
420
+ took the authority `evil.example`, the asterisk form read as the path `/*`,
421
+ and the first of several `Host` lines won.
422
+ 21. **The request signal aborts on a peer disconnect or on
423
+ `RequestOptions.signal`, and on nothing else.** `buildRequest` mints an
424
+ `AbortController`, builds the `Request` over its `signal`, and listens on
425
+ `RequestOptions.signal` until the exchange ends: when the paired
426
+ `RequestOptions.response` closes, or, without one, when the message
427
+ closes. An option signal that aborts in that time aborts the request
428
+ signal with the option signal's own reason; afterward it holds no
429
+ listener of the exchange and aborts nothing. A peer disconnect is the
430
+ message closing before it completed, or the paired response closing
431
+ before it ended. A body cancel, a discarded body, and a finished response
432
+ never abort it. 0.0.22 took no `signal` option and ignored one passed.
433
+ 22. **The request body is pull-based.** For a body-carrying method, the body
434
+ reads the message only when its reader reads, through `readChunk`, with
435
+ `duplex: 'half'` set as Node's fetch implementation requires. An unread
436
+ body holds no more than the message's own buffer whatever the upload
437
+ size, and Node discards it after the response. A cancel discards the
438
+ remainder in place through `discardBody`, and so does the `finish` of the
439
+ paired response, so the connection serves its next request. In 0.0.22
440
+ `buildRequest` pumped the whole upload into the body whether or not a
441
+ reader read it, and a cancel destroyed the message, aborted
442
+ `request.signal`, and left the next request on the connection unanswered.
443
+ 23. **A failed response reads as aborted.** `sendResponse` ends the
444
+ `ServerResponse` with a body that completes in its first chunk, framed by
445
+ its length, and pipes any other non-`null` body through
446
+ `Readable.fromWeb`, which honors backpressure. It removes every listener
447
+ it adds when the exchange ends. A response to a `HEAD` request, and a 1xx, 204, or 304 response,
448
+ carries no body on the wire, so `sendResponse` cancels its body unread and
449
+ ends the target, where 0.0.22 read a `HEAD` response's body to its end and
450
+ Node dropped each write. When the peer closes first, it cancels
451
+ the body, even one waiting for its next chunk, and resolves. When Node
452
+ refuses a header or the body fails, it destroys the target and rejects, so
453
+ the client reads an aborted response, never a truncated one that looks
454
+ complete. In 0.0.22 a failed body ended the target and `sendResponse`
455
+ resolved, so the client read the truncated response as complete.
456
+ 24. **Header fidelity.** `buildRequest` copies every incoming header
367
457
  (multi-value headers comma-joined, except `set-cookie`, appended
368
458
  individually); `sendResponse` writes every outgoing header and re-derives
369
459
  `set-cookie` through `Headers.getSetCookie()` so multiple response cookies
@@ -510,8 +600,11 @@ dispatcher.destroy() // tears down the #emitter; router.entries() is still valid
510
600
 
511
601
  ### Hash-mode navigation
512
602
 
513
- A `Navigator` in hash mode dispatches on `location.hash` and updates `active` after
514
- each `hashchange`:
603
+ A `Navigator` in hash mode dispatches on `location.hash`, updates `active` after each
604
+ `hashchange`, and commits a `navigate` call as it pushes the hash. In 0.0.22 a hash
605
+ `navigate` set `location.hash` and committed after the `hashchange` fired. 0.0.23
606
+ removes the 0.0.22 `navigator.match` method, and `navigator.router.match` answers the
607
+ same lookup, as the following example shows:
515
608
 
516
609
  ```ts
517
610
  import { createNavigator } from '@orkestrel/router/browser'
@@ -524,8 +617,8 @@ const navigator = createNavigator({
524
617
  })
525
618
  navigator.emitter.on('navigate', (match) => (document.title = match.meta.title))
526
619
  navigator.start()
527
- navigator.match('/about')?.meta.title // 'About' — a pure lookup, no location read
528
- navigator.navigate('/about') // sets location.hash; `active` updates after the hashchange fires
620
+ navigator.router.match('/about')?.meta.title // 'About' — a lookup, no location read
621
+ navigator.navigate('/about') // pushes '#/about'; `active` updates before the call returns
529
622
  navigator.stop()
530
623
  navigator.destroy() // stop() plus tear down the #emitter
531
624
  ```
@@ -549,7 +642,16 @@ navigator.start() // binds popstate + same-origin <a> click interception
549
642
  ### Guarding navigation (auth walls)
550
643
 
551
644
  A guard may veto synchronously or asynchronously; a superseded guard's
552
- verdict is discarded through its own `signal`.
645
+ verdict is discarded through its own `signal`. A `navigate` call or an intercepted
646
+ link asks the guard before the URL moves, so a vetoed one leaves the address bar
647
+ alone. In 0.0.22 both moved the URL first and asked the guard after, and no veto moved
648
+ the browser back, so the address bar kept the vetoed location while `active` kept the
649
+ previous match. When the browser moves first, through back, forward, a native fragment
650
+ link, or an address-bar edit, a veto of an entry the navigator wrote moves the
651
+ browser back to the entry `active` describes. For an entry it did not write, the
652
+ address bar keeps the vetoed location while `active` keeps the previous match:
653
+ compare `location` with `active` in your own `hashchange` or `popstate` listener
654
+ and `navigate` to the location you want.
553
655
 
554
656
  ```ts
555
657
  import { createNavigator } from '@orkestrel/router/browser'
@@ -567,12 +669,20 @@ const navigator = createNavigator({
567
669
  navigator.start()
568
670
  ```
569
671
 
570
- ### Basic server
672
+ ### Composing a server
571
673
 
572
- `createListener` adapts a core `Dispatcher` into a `node:http` request listener:
674
+ The server face converts and writes, and your server composes three calls:
675
+ `buildRequest`, `Dispatcher.handle`, and `sendResponse`. The error policy is
676
+ yours. `buildRequest` throws a `ContractError` for a refused target or `Host`,
677
+ which a server can answer with 400, and `sendResponse` has already destroyed
678
+ the connection when it rejects. 0.0.22 exported a `createListener` function
679
+ that composed these three calls and answered a throw before the headers went
680
+ out with a bare 500. 0.0.23 removes it, with `handleListenerRequest`,
681
+ `ListenerFunction`, and `StateFunction`, so compose the calls as the following
682
+ example does:
573
683
 
574
684
  ```ts
575
- import { createListener } from '@orkestrel/router/server'
685
+ import { buildRequest, sendResponse } from '@orkestrel/router/server'
576
686
  import { createDispatcher } from '@orkestrel/router'
577
687
  import http from 'node:http'
578
688
 
@@ -584,36 +694,13 @@ dispatcher.add({
584
694
  Response.json({ id: context.params.id, requestId: context.state.requestId }),
585
695
  })
586
696
 
587
- const server = http.createServer(
588
- createListener(dispatcher, () => ({ requestId: crypto.randomUUID() })),
589
- )
590
- server.listen(0)
591
- ```
592
-
593
- ### Converting requests and responses directly
594
-
595
- For a runtime seam that needs finer control than `createListener` (custom
596
- error handling around `dispatcher.handle`, for instance), compose
597
- `buildRequest`/`sendResponse` directly:
598
-
599
- ```ts
600
- import { buildRequest, sendResponse } from '@orkestrel/router/server'
601
- import { createDispatcher } from '@orkestrel/router'
602
- import http from 'node:http'
603
-
604
- const dispatcher = createDispatcher()
605
- dispatcher.add({ method: 'GET', path: '/health', handler: () => new Response('ok') })
606
-
607
- const server = http.createServer(async (incoming, target) => {
608
- const request = buildRequest(incoming, {
609
- origin: 'https://api.example.com',
610
- response: target,
611
- })
697
+ const server = http.createServer(async (message, target) => {
612
698
  try {
613
- const response = await dispatcher.handle(request, undefined)
699
+ const request = buildRequest(message, { response: target })
700
+ const response = await dispatcher.handle(request, { requestId: crypto.randomUUID() })
614
701
  await sendResponse(response, target)
615
- } catch (error) {
616
- target.writeHead(500).end(String(error)) // this consumer's own error policy
702
+ } catch {
703
+ if (!target.headersSent && !target.destroyed) target.writeHead(500).end() // this consumer's own error policy
617
704
  }
618
705
  })
619
706
  server.listen(0)
@@ -621,16 +708,17 @@ server.listen(0)
621
708
 
622
709
  ### Observing client disconnect
623
710
 
624
- The `Request` returned by `buildRequest` carries a `signal` that aborts when the connection
625
- closes before the response completes:
711
+ The `Request` returned by `buildRequest` carries a `signal` that aborts when the peer
712
+ disconnects, or when the `signal` option aborts, such as a server's own shutdown:
626
713
 
627
714
  ```ts
628
715
  import { buildRequest } from '@orkestrel/router/server'
629
716
  import http from 'node:http'
630
717
 
718
+ const shutdown = new AbortController()
631
719
  const server = http.createServer((incoming, response) => {
632
- const request = buildRequest(incoming, { response })
633
- request.signal.addEventListener('abort', () => console.log('client disconnected'))
720
+ const request = buildRequest(incoming, { response, signal: shutdown.signal })
721
+ request.signal.addEventListener('abort', () => console.log('client gone or server stopping'))
634
722
  })
635
723
  ```
636
724
 
@@ -654,8 +742,12 @@ const server = http.createServer((incoming, response) => {
654
742
  render in the consumer, never inside this headless entity.
655
743
  - **`stop()`/`destroy()` before disposal** — releases listeners and aborts
656
744
  any pending guard; `destroy()` also tears down the `#emitter`.
657
- - **Prefer `createListener` for the common case** — it wires conversion,
658
- dispatch, and the transport-level last-resort `500` together correctly.
745
+ - **Pass the paired response to `buildRequest`** — its `close` aborts the
746
+ request signal on a disconnect after the body, and its `finish` discards a
747
+ body the handler left unread, so a keep-alive connection serves its next
748
+ request.
749
+ - **Cancel a body you stop reading** — a cancel discards the rest of the upload
750
+ in place; it never aborts `request.signal` and never closes the connection.
659
751
  - **Install your own error boundary for mapped error responses** — the
660
752
  router (core and this adapter) never invents one; a handler throw
661
753
  propagates.
@@ -671,7 +763,7 @@ const server = http.createServer((incoming, response) => {
671
763
  interface-to-class method bijection for `RouterInterface`, `GroupInterface`,
672
764
  `DispatcherInterface`, `DispatchGroupInterface`, and `NavigatorInterface`, and the
673
765
  equality gate: every `Summary` cell against its declaration's description paragraph,
674
- the titled `Basic server` fence against the `@example` block of that title (pinned so
766
+ the titled `Register and match` fence against the `@example` block of that title (pinned so
675
767
  the titled pair cannot be retired silently), and the README pitch against this guide's
676
768
  tagline. It also runs the flagship fences this project can execute and asserts the
677
769
  values their comments claim.
@@ -695,12 +787,21 @@ const server = http.createServer((incoming, response) => {
695
787
  with prefixes composed.
696
788
  - [`tests/src/core/helpers.test.ts`](../tests/src/core/helpers.test.ts) —
697
789
  `canonicalizePath`, `computeDispatchKey`, `compilePath` (literal/param/wildcard, escaped
698
- regex metacharacters, trailing-slash folding, case sensitivity, the wildcard-not-final throw),
699
- `decodeParam` (including a malformed `%` escape), `matchPath`,
790
+ regex metacharacters, encoded literals, trailing-slash folding, case sensitivity, and each
791
+ registration refusal), `decodeParam` (including a malformed `%` escape), `matchPath`,
700
792
  `classifySegment` (the literal-vs-param classification fix regression
701
- case), `computeSpecificity`, `compareSpecificity`, `joinPaths`, and
793
+ case), `computeSpecificity`, `compareSpecificity` (tier, then literal length),
794
+ `encodePath`, `collectInputs`, `joinPaths`, and
702
795
  `defineRoute` (identity pass-through, literal `Path` preservation at the
703
796
  call site).
797
+ - [`tests/src/core/integration.test.ts`](../tests/src/core/integration.test.ts) —
798
+ the path matrix: `Router.match` and `Dispatcher.handle` against a reference
799
+ matcher written from the declared grammar, with its own encode set, refusal list,
800
+ and method list, over segment shapes, segment counts, trailing slashes, request
801
+ forms, case rules, methods, and registration orders, through the URL door and the
802
+ raw-text door, with the precedence applied by sort, an order-permutation property,
803
+ the encoder's pairs and a seeded differential, the host row, the registration
804
+ refusals, the batch admission, and the hand-declared rows for each path finding.
704
805
  - [`tests/src/core/parsers.test.ts`](../tests/src/core/parsers.test.ts) —
705
806
  `parseMethod` narrowing every registrable verb, rejecting an unknown verb
706
807
  and the wrong casing, and accepting exactly the verbs `METHOD_LIST`
@@ -710,30 +811,46 @@ const server = http.createServer((incoming, response) => {
710
811
  assertions.
711
812
  - [`tests/src/browser/Navigator.test.ts`](../tests/src/browser/Navigator.test.ts) —
712
813
  hash and history modes, `navigate()`/`active`/`navigate` event, fallback
713
- semantics, guard veto (sync + async, including supersede-discard), link
714
- interception on/off, `start`/`stop`/`destroy` idempotence,
814
+ semantics, guard veto (sync + async, including supersede-discard), the guard
815
+ before the URL moves, the restore after a browser-initiated veto, a `navigate`
816
+ from a `navigate` listener, calls after `destroy`, link interception on/off and
817
+ outside `base`, `base` and hash text compared in one form,
818
+ `start`/`stop`/`destroy` idempotence, every door (history and hash `navigate`,
819
+ the configured and default fallback, raw and encoded text through `router.match`)
820
+ reaching a literal the path encoder changes,
715
821
  `NavigatorInterface` conformance, and the transcriptions of this guide's
716
822
  `@orkestrel/router/browser` fences.
823
+ - [`tests/src/browser/integration.test.ts`](../tests/src/browser/integration.test.ts) —
824
+ the core path grammar on the Chromium host: the host row, and a `|` literal through
825
+ Chromium's URL parsing of `new URL` and `history.pushState`, handed to `new Request` and
826
+ the real dispatcher (no fetch, navigation, or socket runs there).
717
827
  - [`tests/src/browser/factories.test.ts`](../tests/src/browser/factories.test.ts) —
718
828
  `createNavigator` returns a working `NavigatorInterface`.
719
829
  - [`tests/src/browser/helpers.test.ts`](../tests/src/browser/helpers.test.ts) —
720
830
  `computeNavigationKey`, `extractHashPath`, `resolveLocationPath` (hash + history, with/without
721
- `base`), and `findAnchor` (including a click on a styled child inside an
831
+ `base`, a non-ASCII `base`, and `undefined` outside `base`), and `findAnchor` (including a click on a styled child inside an
722
832
  anchor).
723
833
  - [`tests/src/server/validators.test.ts`](../tests/src/server/validators.test.ts) —
724
- `isEncryptedSocket` on an encrypted socket, a plain record, and every
725
- off-shape value.
834
+ `isEncryptedSocket` on a real TLS socket, a plain socket, a plain record, and
835
+ every off-shape value; `isAuthority` over accepted and refused authorities and
836
+ every non-string value.
726
837
  - [`tests/src/server/helpers.test.ts`](../tests/src/server/helpers.test.ts) —
727
- `buildRequest` fidelity (method, URL from `Host`, headers including
728
- multi-value and `set-cookie`, body streaming, the incomplete-request and
729
- complete-request response-side disconnect aborts, plus normal-response
730
- signal/listener cleanup) and `sendResponse` (status, headers including
731
- `set-cookie`, streamed and empty bodies, a destroyed target mid-stream)
732
- over real `node:http` sockets.
733
- - [`tests/src/server/handlers.test.ts`](../tests/src/server/handlers.test.ts) —
734
- `handleListenerRequest` at the transport boundary and `createListener`
735
- end-to-end round-trips (matched, 404, 405, auto-HEAD, auto-OPTIONS, a
736
- handler throw, and per-request state) over real `node:http` sockets.
838
+ `buildURL` by target form, scheme, `Host`, and origin, with each refusal;
839
+ `readChunk` and `discardBody` on a paused message; `buildRequest` fidelity
840
+ (method, URL, headers including multi-value and `set-cookie`, body streaming,
841
+ the incomplete-request abort, and normal-response signal and listener
842
+ cleanup); and `sendResponse` (status, headers including `set-cookie`, bodies,
843
+ backpressure, a disconnect under pressure, and a body that is no stream) over
844
+ real `node:http` sockets.
845
+ - [`tests/src/server/integration.test.ts`](../tests/src/server/integration.test.ts) —
846
+ the HTTP conformance matrix: each row fed to a bare `node:http` control and to
847
+ the adapter, read through a raw client's own framing parse — the target form
848
+ and `Host` tables, the unread body's `bytesRead` at two upload sizes, a cancel
849
+ that leaves the connection reusable, a failed body and a refused header read
850
+ as aborted, the idle-body cancel on disconnect, the request signal, and the
851
+ transport rows (matched, 404, 405, auto-HEAD, auto-OPTIONS, a handler throw,
852
+ and per-request state) through the three-call composition, with the
853
+ `Composing a server` fence transcribed.
737
854
 
738
855
  ## See also
739
856
 
@@ -741,6 +858,6 @@ const server = http.createServer((incoming, response) => {
741
858
  contract & validation architecture, one engine with native overrides,
742
859
  and documentation as contracts.
743
860
  - [`abort.md`](abort.md) — `@orkestrel/abort`, the supersede-safe guard
744
- cancellation primitive the Navigator composes, and the client-disconnect
745
- cancellation primitive the Listener composes.
861
+ cancellation primitive the Navigator composes, and the primitive behind the
862
+ request signal `buildRequest` builds.
746
863
  - [`README.md`](README.md) — the guides index.