@abide/abide 0.103.0 → 0.105.0

package/docs/RULEBOOK.md

@@ -106,11 +106,11 @@ second.
 
 2.4 A failed revalidation MUST NOT cause a read to throw.
 
-2.5 `s[Symbol.asyncIterator]` MUST yield the production in flight from its start, and MUST then
-continue live.
+2.5 On a value that is not a streaming producer, `s[Symbol.asyncIterator]` MUST settle as `s.then`
+does, yielding once what it resolves with.
 
-2.6 On a value that is not a streaming producer, `s[Symbol.asyncIterator]` MUST hand back the
-standing value once per turn, however many productions or patches landed since the last.
+2.6 On a streaming producer, `s[Symbol.asyncIterator]` MUST yield the chunks of the run being served
+from its first, and MUST end when that run closes.
 
 2.7 `s.then` MUST resolve with the value where `s.busy` becomes false and 2.2 would not throw.
 
@@ -270,9 +270,7 @@ the production it serves.
 
 6.9 An expiry MUST NOT report `s.busy` true.
 
-6.10 A cursor MUST NOT be handed an `undefined` production.
-
-6.11 A streaming producer's `ttl` MUST run from its run's close, and MUST NOT reach the run in
+6.10 A streaming producer's `ttl` MUST run from its run's close, and MUST NOT reach the run in
 flight.
 
 # 7. Triggers
@@ -396,6 +394,11 @@ made by one (11.61) MUST end with it.
 9.14 A subscriber's copy of a wired `Reactive` MUST report `s.busy` true until the first production
 arrives.
 
+9.15 A cursor over a streaming producer MUST throw, once it has yielded every chunk, the failure its
+run ended on.
+
+9.16 A cursor over a streaming producer MUST end where a new run replaces the one it was reading.
+
 # 10. Sharing
 
 10.1 `reactive.share` MUST get or create in one call.
@@ -579,6 +582,9 @@ start again when the load ends.
 
 11.70 `s.set` MUST take only a `Reactive` whose `Failures` are this value's.
 
+11.71 An unkeyed `reactive` with a `store`, built on a server outside every request, MUST NOT run
+the `store`'s `get` before it is reached.
+
 # 12. Effects
 
 12.1 A `Disposer` MUST run before each rerun of its `Effect`, and once more at teardown.
@@ -896,7 +902,7 @@ such a call MUST NOT reach it.
 the reader asks for that type and `application/jsonl` otherwise.
 
 16.45 An sse answer MUST frame each value as `data: <json>` followed by a blank line, with
-`text/event-stream`, `no-cache` and `X-Accel-Buffering: no`.
+`text/event-stream` and `cache-control: private, no-store`.
 
 16.46 A stream of value chunks MUST admit jsonl and then sse, and a stream of binary chunks MUST
 admit `application/octet-stream` alone.
@@ -981,6 +987,15 @@ naming it.
 16.74 A module of the client graph importing a handler file MUST receive the wrapper 16.28 states as
 that file's default.
 
+16.75 A streamed answer — jsonl, sse, bytes, or a document `page` hands a stream — MUST carry
+`X-Accel-Buffering: no`.
+
+16.76 An `Rpc` streaming under 16.32 MUST end its answer where the run it sends ends: at that run's
+close, where a new run replaces it, and with the failure that run ended on.
+
+16.77 A `timeout` MUST NOT end a `throttle` or `debounce` window holding a production back, and the
+call MUST wait on that window as 5.15 has it.
+
 # 17. Response helpers
 
 17.1 Every body helper MUST take `Values<T>`.
@@ -1083,6 +1098,10 @@ value again rather than apply what a patch wrote, as 18.12 has it for a version
 18.26 A subscription to a `GET` MUST pass the `middleware` 37.2 runs at the route of the file that
 declared it, as it opens, and MUST NOT be fed where a rung answered in the handler's place.
 
+18.27 A reader of a `text/event-stream` answer — an `Rpc`'s copy and `abide watch` alike — MUST read
+it by the format's fields: a comment skipped, the space after a field's colon optional, `data` lines
+joined, and an event ended by a blank line.
+
 # 19. Mount paths and schemas
 
 19.1 A route MUST be answered for each method by one file at most, a page answering `GET` and `HEAD`
@@ -1164,8 +1183,8 @@ lists a handler for it. What a closed one answers is 36.7.
 
 20.8 Every `/__abide/**` address MUST run inside the app's own middleware.
 
-20.9 `/__abide/mcp` MUST publish a handler that reads as a tool and a resource according to which
-arm `GET` took, and MUST NOT require a flag to tell them apart.
+20.9 `/__abide/mcp` MUST publish every handler it lists as a tool, a `GET` taking no args included,
+and MUST NOT publish one as a resource.
 
 20.10 A handler whose own `Middleware` rung would refuse a caller MUST still be listed, and MUST
 still be refused on the call.
@@ -1294,7 +1313,8 @@ segment a page below it adds.
 
 23.15 A file under a fence MUST NOT have a route.
 
-23.16 A fence under a fence MUST be a build error naming both.
+23.16 A fence under a fence MUST be a build error naming both, save a `server` directory under a
+`lib` or a `tests` directory.
 
 23.17 A route whose first segment is `__abide` MUST be a build error.
 
@@ -1432,8 +1452,7 @@ module ran is not the one served after it.
 27.12 `Config` MUST admit a field an app declares on it, of any type.
 
 27.13 `abide check` and `abide lsp` MUST type `Config` with what the defaults of every `onConfig`
-called as a statement at the top of a `<script server>`, a handler file or a module under a `server`
-directory return, and a union return with the keys
+called as a statement at the top of a `<script server>` or a handler file return, and a union return with the keys
 every member of it has.
 
 # 28. Logging
@@ -1563,12 +1582,16 @@ the page shown, and MUST NOT where only its query or fragment does.
 30.25 A `navigate` that does not remount the page MUST NOT move the scroll, except to the element a
 fragment it carries names.
 
-30.26 `abide check` MUST refuse a `url` literal that no page of the app is filed under and no public
-file of the app is served at.
+30.26 `abide check` MUST refuse a `url` literal that no page route of the app (23.3) is filed under
+and no public file of the app is served at.
 
 30.27 A `navigate` whose request fails, or whose route's chunks fail to load, MUST leave the address
 to the document.
 
+30.28 A `Query` record and the args an `Rpc` carries in its URL MUST be written in one spelling: a
+member left `undefined` omitted, a list its member repeated, an empty list its name with no `=`, and
+anything else its text.
+
 # 31. Reading and writing by name
 
 31.1 Inside a `.abide` file a name bound to a `Reactive` MUST be read wherever 31.3 does not hold it.
@@ -2042,7 +2065,8 @@ answered per 41.12.
 
 37.1 A lifecycle hook MUST be filed at the route of the `.abide` or the handler file that called it,
 one under a `lib` or a `tests` directory at the route of the directory holding that one, and at the
-root route where neither did.
+root route where neither did; a call MUST be read as a hook only where it names a hook the module
+imports from abide, under any name, or a member of a namespace it imports from abide.
 
 37.2 `middleware` filed below the root route MUST run after routing, over a request its route or a
 route below it answers, outermost route first.
@@ -2079,6 +2103,9 @@ through `App.stop`, and the process MUST then exit with 0.
 
 37.12 A second `SIGTERM` or `SIGINT` while the app is stopping MUST end the process at once.
 
+37.13 A lifecycle hook called in a module of the app's own that is neither a `.abide` nor a handler
+file MUST be a build error naming the module and the hook.
+
 # 38. Commands
 
 38.1 `abide scaffold` MUST write a starter project, and MUST skip a step already done.
@@ -2139,7 +2166,8 @@ link none where the build bundled none.
 by the replacement.
 
 38.25 `--root` MUST default to `src` where the working directory holds one, and to the working
-directory otherwise.
+directory otherwise; and the app it finds MUST be the one the whole command means — what it builds,
+boots, serves and announces.
 
 38.26 A command that finds no app at its `--root` MUST fail, naming where it looked.
 
@@ -2163,7 +2191,7 @@ warnings alone.
 every file that refusal does not stop.
 
 38.34 `abide lsp` MUST report what 38.3 reports, over the text the editor holds rather than the
-text on disk.
+text on disk, and every refusal the app's tree makes of the file, as the tree was last saved.
 
 38.35 `abide dev` MUST send a response body as the app produces it.
 
@@ -2385,6 +2413,11 @@ with `--json` it MUST print the same as one JSON document.
 38.109 Under `bun test` with `@abide/abide/test` preloaded, a test MUST import a `.abide` of the app as
 the module it compiles to, whether or not `createApp` has run.
 
+38.110 A build `abide start`, `abide call`, `abide openapi` or `abide mcp` makes first (38.100) MUST
+be reported on stderr, leaving the command's stdout to its own output.
+
+38.111 `abide openapi` MUST print the OpenAPI document on stdout.
+
 # 39. Head and view transitions
 
 39.1 A `<head>` element in a `.abide` file MUST contribute its children to the document head.
@@ -2396,7 +2429,8 @@ the module it compiles to, whether or not `createApp` has run.
 39.4 `<head>` contributions MUST be merged by key, and the deepest contributor MUST win. The shell's
 `<head>` MUST be the outermost contributor.
 
-39.5 A `<head>` contribution with no merge key MUST append in tree order.
+39.5 A `<head>` contribution with no merge key MUST append — in tree order among the contributions
+its level mounts with, and when it mounts for a component mounted after its level.
 
 39.6 On a client navigation the incoming page's keyed `<head>` contributions MUST replace the
 outgoing page's by key, and a layout's MUST NOT move.
@@ -2418,12 +2452,19 @@ app MUST NOT be required to feature-detect.
 
 39.12 The last `<head>` contribution for a key within one file MUST win.
 
-39.13 In a browser, a `<head>` contribution that reads a value MUST follow it for as long as its page
-or layout is mounted.
+39.13 In a browser, a `<head>` contribution that reads a value MUST follow it for as long as the
+page, layout or component that made it is mounted.
 
-39.14 On a client navigation, a keyed `<head>` contribution that a leaving page or layout made and
-no arriving one makes MUST return to the nearest kept layout's value for its key, and MUST be removed
-where no kept layout has that key.
+39.14 When a page, layout or component leaves — on a client navigation, or with its region — a keyed
+`<head>` contribution it made and no deeper contributor still makes MUST return to the nearest
+remaining outer contributor's value for its key, and MUST be removed where no remaining outer
+contributor has that key.
+
+39.15 A `<head>` contribution with no merge key that its page, layout or component writes again
+MUST replace, in place, the one that same contributor wrote before.
+
+39.16 A `<head>` contribution with no merge key MUST be removed when the page, layout or component
+that made it leaves.
 
 # 40. Documentation
 
@@ -2595,6 +2636,9 @@ has answered or failed.
 41.27 An `Rpc` call `render` built the page's markup from in flight MUST be in flight as hydration
 adopts the page, however early its answer arrived.
 
+41.28 A `render` MUST let the turn's queued microtasks run between setting up a `<Name/>` whose setup
+made an `Rpc` call and building that component's markup.
+
 # 42. The app object
 
 42.1 `createApp` MUST build the route table and compose every `Middleware` rung, per 16.14.

package/docs/abide.md

@@ -573,7 +573,7 @@ Read on: [Head & metadata](/pages/set-the-title-and-social-preview.md) · [Layou
 
 Rendering a page runs its setup: the `<script>` blocks, the `reactive` calls, the bodies the markup reads. Each read that needs the server starts its work immediately, so the loads on a page are in flight together rather than in the order the markup happens to mention them.
 
-The total time is the slowest one, not the sum — and the first byte does not wait for any of them. The markup waits one turn, so a load that answers without waiting on anything is painted rather than left as a hole.
+The total time is the slowest one, not the sum — and the first byte does not wait for any of them. The markup waits one turn, so a load that answers without waiting on anything is painted rather than left as a hole. A component whose setup starts a load gets the same turn before its own markup is built, however deep it sits.
 
 ## 4. The first bytes leave
 
@@ -1597,11 +1597,11 @@ Read on: [Throttle & debounce](/values/slow-down-a-value-that-changes-too-fast.m
 
 ## Following a channel sees turns, not every message
 
-`for await (const turns of onboarding)` walks the channel's cursor. On a value with no streaming producer the cursor hands back the standing value once per turn, however many writes landed since the last, and a patch in place is one of them (2.6). A burst of three messages in one turn is one step, holding all three.
+`onboarding.watch((turns) => …)` follows the channel. The effect runs once at the end of a turn, however many writes landed in it, and a patch in place is one of them (12.10). A burst of three messages in one turn is one run, holding all three.
 
-So there is no exactly-once tail of a channel. Code that has to act on every message acts where it writes it — in `say`, beside the push. The cursor never hands back an `undefined` value (6.10).
+So there is no exactly-once tail of a channel. Code that has to act on every message acts where it writes it — in `say`, beside the push.
 
-A stream is the other case: its cursor yields from the start of the run in flight and then live, one step per chunk (2.5), and a capped window still delivers every chunk (5.10).
+`for await` is not a follow. Over a value it yields the settled value once and ends, as `await` does (2.5). Over a stream it yields each chunk of the run and ends at the close (2.6), and a capped window still delivers every chunk (5.10).
 
 Read on: [Watching values](/values/do-something-when-a-value-changes.md) · [Streaming data](/data/send-data-as-it-arrives.md)
 
@@ -2506,7 +2506,7 @@ Two costs, and both are yours rather than abide's.
 
 And a global value is bounded by its own `ttl` and the app's `invalidate` and by nothing else. There is no byte ceiling and no eviction count: measuring an arbitrary value costs an O(size) walk, and an LRU would evict an entry a reader is mid-flight on. `global: true` with `ttl: Infinity` is an unbounded cache — unbounded because the app asked for it, the bound being a number the app knows and abide does not.
 
-A global value over a stream fans one producer out to many readers, and it needs no retention to do it. A reader arriving mid-stream gets the run in flight from its start and then goes live (2.5), and a reader leaving does not cancel the producer for the ones that remain (11.39).
+A global value over a stream fans one producer out to many readers, and it needs no retention to do it. A reader arriving mid-stream gets the run in flight from its first chunk to its close (2.6), and a reader leaving does not cancel the producer for the ones that remain (11.39).
 
 Read on: [Recent values](/values/keep-the-last-few-values.md) · [Auth & principal](/app/know-who-is-calling.md) · [Authorization](/data/decide-who-may-call-what.md) · [Response types](/data/answer-with-something-other-than-json.md)
 
@@ -3652,7 +3652,7 @@ Read on: [Patching a list](/values/patch-a-list-from-a-live-feed.md) · [Lists](
 
 Every `Reactive` holds its standing value and nothing before it. Where you want the ones before it, hold them: make the value the array, and append where you write.
 
-A reader cannot build the window for you. `for await` over a value hands back the standing value once per turn, and a burst of writes in one turn is one step (2.6), so a window a reader assembles misses whatever landed in the same turn. The writer sees every value, which is why the window is built where the write is.
+A reader cannot build the window for you. A `watch` runs once per turn, and a burst of writes in one turn is one run (12.10), so a window a reader assembles misses whatever landed in the same turn. The writer sees every value, which is why the window is built where the write is.
 
 A channel is this same shape with many writers — a `reactive` over an array that everyone connected reads, trimmed the same way.
 
@@ -4930,7 +4930,7 @@ Each takes `Values<T>`, and sse is reachable from jsonl without declaring it: se
 
 ## An async generator streams as JSON Lines
 
-A handler returning an `AsyncGenerator` is framed as **jsonl** — one JSON value per line, `application/jsonl`, or `application/x-ndjson` for a reader that asks for NDJSON by name (16.44). The body is written per `pull`, so back-pressure reaches your database cursor rather than piling rows up in memory.
+A handler returning an `AsyncGenerator` is framed as **jsonl** — one JSON value per line, `application/jsonl`, or `application/x-ndjson` for a reader that asks for NDJSON by name (16.44). The body is written per `pull`, so back-pressure reaches your database cursor rather than piling rows up in memory, and it carries `X-Accel-Buffering: no`, as every streamed answer does, so a proxy in front passes each line on as it arrives (16.75).
 
 That is the default framing and not the only one.
 
@@ -4986,7 +4986,7 @@ const feed = reactive(async () => {
 *1 helper, 0 lines of framing* — the arm writes `data: `, the blank line after it and the two headers a proxy needs to leave the stream alone, by hand, per event.
 
 The card's request carries no `Accept`, which is what a wallboard script or a `curl` sends, and without `sse` that caller is answered jsonl. A caller that does ask — an `EventSource` sends `Accept:
-        text/event-stream` — gets the same events from a handler that never declared them: the jsonl transcript reframed as `data: <json>` per line with a blank line after it, `no-cache` and `X-Accel-Buffering: no`. That is one URL with two bodies, so it carries `vary: accept`. Declaring `sse` is for the caller who cannot say what it wants. The `:` the card's answer opens on is a comment, which sends the head before the first event exists.
+        text/event-stream` — gets the same events from a handler that never declared them: the jsonl transcript reframed as `data: <json>` per line with a blank line after it, under `private, no-store` like any rpc answer. That is one URL with two bodies, so it carries `vary: accept`. Declaring `sse` is for the caller who cannot say what it wants. The `:` the card's answer opens on is a comment, which sends the head before the first event exists.
 
 Read on: [Response types](/data/answer-with-something-other-than-json.md)
 
@@ -5176,7 +5176,7 @@ Read on: [Loading states](/values/show-a-value-that-isnt-there-yet.md) · [Lists
 
 ## A reader arriving mid-run replays the run
 
-There is no retention option on the transport and none is owed. What a late reader needs is the answer being built, and a cursor over the stream hands it the run in flight from its start before it goes live (2.5). So a reader arriving halfway through still paints every row.
+There is no retention option on the transport and none is owed. What a late reader needs is the answer being built, and a `for await` over the stream hands it the run in flight from its first chunk to its close (2.6). So a reader arriving halfway through still paints every row.
 
 ## A stream is not a channel
 
@@ -5386,7 +5386,7 @@ The call hands back the same `Reactive` the handler had, `Produced` included (16
 
 Writing to that copy is not how to send. A `set` on it stands only until the next production replaces it (9.4), so a turn goes through `say`.
 
-`room.invalidate({ id })` and `room.refresh({ id })` inside a handler reach every browser's copy of that room (7.10, 7.18). A `for await` over the room hands back the standing array once per turn, a burst collapsing to the latest (2.6), so code that has to act on every message acts in `say`.
+`room.invalidate({ id })` and `room.refresh({ id })` inside a handler reach every browser's copy of that room (7.10, 7.18). A `watch` on the room runs once per turn, a burst collapsing to the latest (12.10), so code that has to act on every message acts in `say`.
 
 ## Each instance holds its own room
 
@@ -7220,7 +7220,7 @@ Read on: [Streaming HTML](/pages/send-the-page-before-the-data-lands.md) · [Req
 
 The incoming page's keyed contributions replace the outgoing page's **by key**. A layout's contributions do not move at all, the layout not having been rebuilt — so the app's icon and its font preloads are declared once and never touched again.
 
-A key only the outgoing page set goes back to the layout's value, and is removed where no layout has one. The tab ends on the title a fresh load of that address shows.
+A key only the outgoing page set goes back to the layout's value, and is removed where no layout has one, and what it appended with no key leaves with it. The tab ends on the title a fresh load of that address shows.
 
 Read on: [Links & navigation](/pages/link-to-another-page.md)
 
@@ -9229,27 +9229,10 @@ Read on: [Config](/app/configure-the-app.md) · [Authorization](/data/decide-who
 
 ## A root rung answers what no route does
 
-`middleware` filed at the root route runs before routing, so a rung there can answer an address no page or handler claims, and hand everything else on with `next()`. These docs serve every page as markdown that way:
-
-```ts src/lib/downloads.ts — excerpt
-middleware(async (next, { request }) => {
-    const { pathname, origin } = new URL(request.url)
-    if (!pathname.endsWith('.md') && !pathname.endsWith('/llms.txt'))
-        return next()
-    if (pathname === '/llms.txt')
-        return new Response('# abide\n\nEvery page, as markdown: abide.md\n')
-    if (pathname === '/abide.md') {
-        bundled ??= bundle(origin)
-        return new Response(await bundled, { headers: MARKDOWN })
-    }
-    for (const group of SITE)
-        for (const page of group.pages)
-            if (pathname === markdownAddressOf(page.route))
-                return new Response(await pageMarkdown(page.route, origin), {
-                    headers: MARKDOWN,
-                })
-    return next()
-})
+`middleware` filed at the root route runs before routing, so a rung there can answer an address no page or handler claims, and hand everything else on with `next()`. These docs serve every page as markdown that way — the rung is a module's export, and the root layout files it with `middleware(serveDownloads)`, since a hook is only called in a page, a layout or a handler file (37.13):
+
+```ts src/lib/serveDownloads.ts — excerpt
+export const serveDownloads: Middleware<
 ```
 
 It uses the same response helpers everything else does, there being no second set.
@@ -10006,13 +9989,15 @@ let refused = reactive('—')
 <script server>
 // The docs app's own hooks; each example files its own in its own file.
 import { csp, middleware, onConfig } from '@abide/abide/server'
-import '#src/lib/downloads.ts'
+import { serveDownloads } from '#src/lib/serveDownloads.ts'
 
 // The sign-in examples need a secret: one per process, or the deployment's.
 const PRINCIPAL_SECRET = crypto.randomUUID()
 
 onConfig(() => ({ ABIDE_PRINCIPAL_SECRET: PRINCIPAL_SECRET }))
 
+middleware(serveDownloads)
+
 // Every docs page's policy; 'self' so the docs can frame invoice previews.
 middleware(csp({ 'frame-ancestors': ["'self'"] }))
 </script>
@@ -10276,10 +10261,10 @@ The address runs inside the app's own middleware like every `/__abide/**` addres
 ## Written rather than served
 
 ```
-abide openapi --out dist/openapi.json
+abide openapi > dist/openapi.json
 ```
 
-The same document, produced from the source rather than asked of a server. That is what a build step wants — a spec committed beside the code, or handed to a client generator — and it does not require the app to be running or the address to be on.
+The same document, printed from the source rather than asked of a server. That is what a build step wants — a spec committed beside the code, or handed to a client generator — and it does not require the app to be running or the address to be on.
 
 `--url` points it at a running app instead, which is what you want when the question is what *that deployment* is serving.
 
@@ -10307,11 +10292,11 @@ Read on: [Withholding a surface](/machines/keep-a-handler-off-a-surface.md)
 
 An MCP server is a list of tools with typed arguments and descriptions. A declared handler is a typed argument shape with a description. `/__abide/mcp` is the second read as the first, over streamable http.
 
-## The method decides tool or resource
+## Every handler is a tool
 
-A handler is published as a **tool** or as a **resource** according to which arm `GET` took, and no flag tells them apart. A read is a resource, a mutation is a tool — which is the distinction MCP already draws, arrived at from the declaration rather than from an annotation somebody has to keep true.
+Every handler the route table publishes is a **tool** — a read that takes no arguments as much as a mutation. None is published as an MCP resource, because a client that only calls tools, Claude Code under `abide-bridge` among them, would never reach a handler listed as one.
 
-That is the whole of the mapping, and it is worth being able to state in one line: the model sees your app's verbs because your app already declared which of its handlers change something.
+That is the whole of the mapping: the model sees every handler your app publishes, and whether one changes something is the handler's own method, not a second listing.
 
 ## The description is the handler's
 
@@ -11810,8 +11795,8 @@ Every `Reactive` takes these, whichever overload made it.
 | `s.then` | `<Result>(onSettled?: (value: Stored) => Result \| PromiseLike<Result>, onFailed?: (error: unknown) => Result \| PromiseLike<Result>) => Promise<Result>` | The settling, as a promise. Resolves when `busy()` goes false, and rejects with what a read would throw. |
 | `s.catch` | `<Result>(onFailed: (error: unknown) => Result \| PromiseLike<Result>) => Promise<Stored \| Result>` | The settling's refusal path, derived from `then`. Fires for a producer that failed with nothing landed, and for nothing else. |
 | `s.finally` | `(onSettled: () => void) => Promise<Stored>` | The settling's end, whichever way it went. What ends is the settling, not the value — a subscriber's copy of a channel settles at its first production and goes on. |
-| `for await (… of s)` | `AsyncIterable<Produced>` | The live cursor face of a read. On a stream, one turn per chunk. On any other value, the standing value once per turn — a burst collapses to the latest, and an in-place `patch` is a turn of its own. |
-| `s[Symbol.asyncIterator]` | `() => AsyncIterator<Produced>` | The production in flight from its start, and then what follows it. A chunk is a piece of one value, so a stream's cursor sees every chunk; any other value's cursor sees where the value stands. |
+| `for await (… of s)` | `AsyncIterable<Produced>` | What one run produced. On a stream, one turn per chunk, ending at the close and throwing what failed the run. On any other value, the settled value once, as `await` gives it. To follow changes, `watch`. |
+| `s[Symbol.asyncIterator]` | `() => AsyncIterator<Produced>` | The run being served, from its start to its end. A chunk is a piece of one value, so a stream's cursor sees every chunk; any other value's cursor sees the value it settles on. |
 
 ## Writes
 
@@ -12843,7 +12828,7 @@ src/
 
 A route is its file's path without the extension, and an `index.abide`, a `layout.abide` and an `error.abide` take their directory's (23.14). Every other `.abide` directly in a directory is a page (23.21), so a component lives under a `lib`. A `.ts` there is a handler file.
 
-`lib`, `tests`, `server` and `public` are the fences, and nothing under one has a route (23.15). One inside another is a build error, and so is an `index.abide`, a `layout.abide` or an `error.abide` under one (23.16, 23.18). A directory's top level holds pages, layouts, error pages, handler files, directories and fences alone — any other file there is a build error naming the `lib` to move it into (23.22). So listing a directory lists its routes, and `abide routes` lists the app's.
+`lib`, `tests`, `server` and `public` are the fences, and nothing under one has a route (23.15). One inside another is a build error, save a `server` inside a `lib` or a `tests`, which keeps code only the server loads beside the components that call it — and so is an `index.abide`, a `layout.abide` or an `error.abide` under one (23.16, 23.18). A directory's top level holds pages, layouts, error pages, handler files, directories and fences alone — any other file there is a build error naming the `lib` to move it into (23.22). So listing a directory lists its routes, and `abide routes` lists the app's.
 
 ### Resolution order
 
@@ -12967,7 +12952,7 @@ A page and a handler file are **addresses rather than names**, and so are `index
 | `onPrincipal` | `(resolve: (claims: unknown) => unknown \| Promise<unknown>) => () => void` | Turns claims into the app's half of a principal. |
 | `onLauncher` | `(options: () => LauncherOptions) => () => void` | The window the desktop app opens and the forms its launcher offers. |
 
-Each is a hook you **call** rather than an export the framework looks for, a `.abide` exporting nothing. It is filed at the route of the `.abide` or the handler file that called it, and at the root where a module called it (37.1). A `.abide` under a `lib` or a `tests` directory files its hooks at the route of the directory holding that one. `onLauncher` is called in `src/launcher.abide` alone.
+Each is a hook you **call** rather than an export the framework looks for, a `.abide` exporting nothing. It is filed at the route of the `.abide` or the handler file that called it (37.1), and any other module calling one is a build error (37.13) — export the function and call the hook where it serves. A `.abide` under a `lib` or a `tests` directory files its hooks at the route of the directory holding that one. `onLauncher` is called in `src/launcher.abide` alone.
 
 `middleware` runs over that route and the ones below it — before routing at the root, after it anywhere else — and `onError` hears an error there, nearest route first. The rest are the process's wherever they are written, and every one of a kind composes: `onConfig` and `onPrincipal` merge what each answers, the deeper route's over the root's. `abide routes` lists every call with the route it is filed at.
 
@@ -12985,7 +12970,7 @@ Every one hands back the way off again, so a module that is torn down can remove
 
 ### `Config` is typed from the `onConfig` calls
 
-`abide check` and `abide lsp` type `Config` from the defaults every `onConfig` returns, read where it is called as a statement at the top of a `<script server>`, of a handler file or of a module under a `server` directory (27.13). A default that returns a union types the keys every member of it has. So a config read is typed without a declaration of its own, wherever in the app the default is written.
+`abide check` and `abide lsp` type `Config` from the defaults every `onConfig` returns, read where it is called as a statement at the top of a `<script server>` or of a handler file (27.13). A default that returns a union types the keys every member of it has. So a config read is typed without a declaration of its own, wherever in the app the default is written.
 
 ### `NODE_ENV` is verbatim
 
@@ -13047,7 +13032,7 @@ abide --help
 - `--port <n>` — the listen port for `dev` and `start`. Defaults to `PORT`, then to 3000 — where `dev` moves on to the first free port through 3099.
 - `--root <dir>` — the app's source directory. Defaults to `src` where you are standing, and to where you are standing when there is none — so `cd ledger && abide dev` and `abide dev --root
                 ./src` are the same command. A directory holding no `.abide` under a `package.json` is not an app, and the command says so rather than building nothing.
-- `--out <dir>` — where `build` writes, beside the app rather than beside you: building `packages/ledger/src` from anywhere leaves `packages/ledger/.abide`, which is where `start` looks. It is also the file `openapi` and `compile` write, rather than standard output.
+- `--out <dir>` — where `build` writes, beside the app rather than beside you: building `packages/ledger/src` from anywhere leaves `packages/ledger/.abide`, which is where `start` looks. It is also the file `compile` and `bundle` write.
 - `--url <origin>` — the running app the shell, `openapi`, `mcp`, `call` and `logs` talk to. Defaults to `ABIDE_APP_URL`, then to the local app.
 - `--target`, `--platforms` — what `compile` builds for.
 
@@ -13071,7 +13056,7 @@ abide --help
 | `abide start [--port <n>]` | Boots the built app. |
 | `abide [--url <origin>] [--port <n>]` | The interactive shell — on the built app it boots, or on the running app `--url` names. |
 | `abide call <address> [args]` | One call to one handler. |
-| `abide openapi [--out <file>] [--url <origin>]` | The OpenAPI document written rather than served. |
+| `abide openapi [--url <origin>]` | The OpenAPI document printed rather than served. |
 | `abide mcp [--url <origin>]` | The app's MCP server over stdio. |
 | `abide watch <address> [args]` | A live subscription to one of the app's followed `GET`s. |
 | `abide compile [--target] [--out] [--platforms]` | One standalone executable. |
@@ -13115,7 +13100,7 @@ abide call invoices/getInvoice id=4310
 ### Write the OpenAPI document at build time
 
 ```
-abide openapi --out dist/openapi.json
+abide openapi > dist/openapi.json
 ```
 
 ## See also

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@abide/abide",
-    "version": "0.103.0",
+    "version": "0.105.0",
     "type": "module",
     "description": "Isomorphic type-safe framework for reactive async interfaces for humans and machines",
     "license": "MIT",

package/src/compiler/Lowering.ts

@@ -33,6 +33,12 @@ import { nesting, type Token, tokenize } from './tokenize.ts'
 // no parentheses to survive one.
 const SHORT_CIRCUIT: ReadonlySet<string> = new Set(['||', '&&', '??'])
 
+/** 23.9 — a page's or a layout's route, which its `route.params` promises. */
+export type Routed = { route: string; kind: 'page' | 'layout' }
+
+/** A run of emitted code a `Lowering` wrote, and where each of its runs stood in the projection. */
+export type LoweredChunk = { text: string; origins: Origin[] }
+
 /**
  * One file's lowering: each piece the emitters ask for, with its reactive reads rewritten.
  *
@@ -42,9 +48,6 @@ const SHORT_CIRCUIT: ReadonlySet<string> = new Set(['||', '&&', '??'])
  * so the import goes with the call; left to the callers it is one `used.add` per call site and a
  * missed one emits a module calling a name it never imported.
  */
-/** A run of emitted code a `Lowering` wrote, and where each of its runs stood in the projection. */
-export type LoweredChunk = { text: string; origins: Origin[] }
-
 export class Lowering {
     readonly projection: Projection
     readonly used = new Set<string>()
@@ -85,18 +88,25 @@ export class Lowering {
      * the projection: what `sourceMapOf` finds in the module the emitter writes.
      */
     private readonly chunks: LoweredChunk[] | undefined
+    /**
+     * 23.9 — for a checked lowering of a page or a layout, its route and which of the two it is:
+     * what its `route.params` is typed by.
+     */
+    private readonly routed: Routed | undefined
 
     constructor(
         file: AbideFile,
         answer: CheckerAnswer,
         checking = false,
         chunks?: LoweredChunk[],
+        routed?: Routed,
     ) {
         this.projection = projectShadow(file)
         this.answer = answer
         this.holdsSlot = holdsSlot(file.template)
         this.checking = checking
         this.chunks = chunks
+        this.routed = routed
     }
 
     /**
@@ -441,8 +451,8 @@ export class Lowering {
         const spelled = this.projection.text.slice(read.start, read.end)
         // 23.9 — WHAT THIS PAGE'S OWN ROUTE PROMISES, for the checker alone: the running module
         // reads the one `route` every page shares.
-        if (this.checking && read.routeParams !== undefined)
-            return `(${spelled} as unknown as () => __RouteParams<${JSON.stringify(read.routeParams[0])}, ${JSON.stringify(read.routeParams[1])}>)`
+        if (this.routed !== undefined && read.routeParams)
+            return `(${spelled} as unknown as () => __RouteParams<${JSON.stringify(this.routed.route)}, ${JSON.stringify(this.routed.kind)}>)`
         return read.through ? `${spelled}()` : spelled
     }
 

package/src/compiler/Refusals.ts

@@ -0,0 +1,57 @@
+import { resolve } from 'node:path' // bun exposes no path helpers of its own
+import { formatDiagnosis } from './formatDiagnosis.ts'
+import { diagnosisAt } from './lineOf.ts'
+import type { Diagnosis } from './TypeSession.ts'
+
+/**
+ * Where everything the compile refuses goes, each at the file it was refused in.
+ *
+ * TWO MODES AND ONE CALL: a build stops at a refusal, so a throwing sink throws it; `abide
+ * check` reports every one at its file and goes on (38.33), so a collecting sink keeps each as a
+ * finding at the file's first line. Every stage takes this and nothing else, so no stage decides for
+ * itself what a refusal does, and none spells a path its own way: a file is named relative to `root`
+ * or absolutely, and kept absolute.
+ */
+export class Refusals {
+    /** Every refusal kept, in the order met; empty in a throwing sink. */
+    readonly found: Diagnosis[] = []
+    /** What a file below the root is named relative to. */
+    readonly root: string
+    /** Whether a refusal is kept and the compile goes on, rather than thrown. */
+    readonly collecting: boolean
+
+    constructor(root: string, collecting: boolean) {
+        this.root = root
+        this.collecting = collecting
+    }
+
+    /** Refuses at `file`, below the root or absolute: `thrown` is thrown, or kept. */
+    at(file: string, thrown: unknown): void {
+        if (!this.collecting) throw thrown
+        this.found.push(
+            diagnosisAt(
+                resolve(this.root, file),
+                undefined,
+                0,
+                'error',
+                thrown instanceof Error ? thrown.message : String(thrown),
+            ),
+        )
+    }
+
+    /**
+     * What another stage kept, as this one takes it: every one kept, or every one thrown as one
+     * error, each at its file — a build that stops names all it found rather than a first one and a
+     * second run (11.37).
+     */
+    adopt(found: readonly Diagnosis[]): void {
+        if (found.length === 0) return
+        if (this.collecting) {
+            this.found.push(...found)
+            return
+        }
+        const lines: string[] = []
+        for (const one of found) lines.push(formatDiagnosis(one, process.cwd()))
+        throw new Error(lines.join('\n'))
+    }
+}