@abide/abide 0.104.0 → 0.105.0

package/docs/RULEBOOK.md

@@ -582,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.
@@ -899,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.
@@ -984,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>`.
@@ -1086,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`
@@ -1566,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.
@@ -2045,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.
@@ -2145,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.
 
@@ -2169,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.
 
@@ -2391,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.
@@ -2402,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.
@@ -2424,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 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.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.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
 
@@ -2601,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
 
@@ -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)
 
@@ -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)
 
@@ -10261,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.
 
@@ -13032,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.
 
@@ -13056,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. |
@@ -13100,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.104.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'))
+    }
+}

package/src/compiler/TypeSession.ts

@@ -11,10 +11,10 @@ import {
     SignatureKind,
     SymbolFlags,
 } from 'typescript/unstable/async'
-import { appFiles } from '#server/appTree.ts'
-import { fileKind, placeOf, routeOf } from '#shared/routePattern.ts'
+import { placeOf } from '#server/placement.ts'
 import { aliasedSymbol } from './aliasedSymbol.ts'
 import { AMBIENT_SOURCES, ambientReadsIn } from './ambientReadsIn.ts'
+import type { AppLayout, PlacedSource } from './appLayout.ts'
 import { argsDefaultsIn } from './argsDefaultsIn.ts'
 import { type CheckerAnswer, UNCHECKED } from './CheckerAnswer.ts'
 import {
@@ -26,7 +26,6 @@ import {
 import type { Finding } from './Finding.ts'
 import { CHECKED_VALUES } from './Lowering.ts'
 import { diagnosisAt, lineOf } from './lineOf.ts'
-import { mountedUnder } from './mountsOf.ts'
 import type { AbideFile } from './parseAbide.ts'
 import { projectShadow } from './projectShadow.ts'
 import { abideIn } from './reactiveTypes.ts'
@@ -65,18 +64,6 @@ export class TypeSession {
      * text's offsets.
      */
     private shadows = new Map<string, { path: string; text: string }>()
-    /**
-     * What `diagnose` last read off one walk of the root: the route table it declared (30.26) and the
-     * modules it read for their `onConfig` (27.13). Kept until `edited` hears anything move, so a
-     * check asked again and again while an editor types walks and reads nothing on disk.
-     */
-    private walked:
-        | {
-              within: string
-              routes: string
-              configModules: Promise<[string, string][]>
-          }
-        | undefined = undefined
     /** The checker's own key for a path: resolved, and case-folded where its host folds case. */
     private keyOf: (path: string) => string
     /**
@@ -358,7 +345,6 @@ export class TypeSession {
      * checker is not told what was under it.
      */
     edited(paths: string[] | undefined): void {
-        this.walked = undefined
         if (paths === undefined) {
             this.everything = true
             return
@@ -447,10 +433,12 @@ export class TypeSession {
     }
 
     /**
-     * 34.25, 23.19 — makes `path`, a dependency's file, a root of the opened config, telling
-     * `changed` the config moved where it was not one already.
+     * 34.25, 23.19 — where `source` is a dependency's file, makes `path` — it, or what it lowers to
+     * — a root of the opened config, telling `changed` the config moved where it was not one
+     * already. The app's own is a root already: telling the config it moved reloads the project.
      */
-    private openOutside(path: string, changed: string[]): void {
+    private openOutside(source: string, path: string, changed: string[]): void {
+        if (placeOf(this.belowRoot(source)) !== 'dependency') return
         if (this.outside.has(path)) return
         this.outside.add(path)
         if (!changed.includes(this.opened)) changed.push(this.opened)
@@ -472,9 +460,7 @@ export class TypeSession {
         const changed: string[] = []
         for (const path of modules) {
             const canonical = this.canonical(path)
-            // The app's own is a root already: telling the config it moved reloads the project.
-            if (placeOf(this.belowRoot(canonical)) === 'dependency')
-                this.openOutside(canonical, changed)
+            this.openOutside(canonical, canonical, changed)
         }
         const project = await this.currentProject([], changed)
         if (project === undefined) return project
@@ -574,7 +560,6 @@ export class TypeSession {
     async readsFor(
         sources: readonly (Pick<ParsedSource, 'path' | 'file'> & {
             text?: string
-            position?: string | undefined
         })[],
     ): Promise<{ answers: CheckerAnswer[]; warnings: Diagnosis[] }> {
         const answered = await this.classify(sources)
@@ -597,7 +582,6 @@ export class TypeSession {
     private async classify(
         sources: readonly (Pick<ParsedSource, 'path' | 'file'> & {
             text?: string
-            position?: string | undefined
         })[],
     ): Promise<{ answers: CheckerAnswer[]; warnings: Diagnosis[] }> {
         const warnings: Diagnosis[] = []
@@ -646,8 +630,7 @@ export class TypeSession {
             // AN UNCHANGED SHADOW IS NOT REPORTED, which is what a kept session saves on a save:
             // the one page that moved is re-read rather than all of them.
             this.register(map.shadowPath, projection.text, created, changed)
-            if (placeOf(this.belowRoot(source.path)) === 'dependency')
-                this.openOutside(map.shadowPath, changed)
+            this.openOutside(source.path, map.shadowPath, changed)
             queries.push({
                 map,
                 spans: {
@@ -690,8 +673,6 @@ export class TypeSession {
                     sourceFile,
                     query.map.shadowPath,
                     query.spans,
-                    // 23.19 — a mounted page's route is its position's.
-                    source.position ?? this.belowRoot(source.path),
                     source.file,
                 )
                 answers[at] = read.answer
@@ -812,22 +793,27 @@ export class TypeSession {
      * 38.3 — WHAT THE CHECKER SAYS ABOUT EACH FILE AS IT RUNS, placed on the `.abide` line. Each
      * source is checked as its lowered program (`checkedShadow`), which is registered for the life
      * of the session beside its shadow for the reason a shadow is; and every `.ts` root of the
-     * project under `within` is checked as it stands, where `scripts` asks for them — an editor
+     * project under the app's root is checked as it stands, where `scripts` asks for them — an editor
      * asking about one page does not want the whole app. `sources` carry their text, which is what
      * a position is a line of. A `quiet` source is lowered and not reported on: a component an
      * editor's page imports, which is there for the props the page is held to (33.4).
      *
+     * `app` is the app the sources are checked in (`appLayout`): its route table, which `url`'s
+     * literal is held to (30.26), and its handler files, which type `Config` (27.13). A source placed
+     * as a page or a layout carries its `kind` and `route`, which its `route.params` is typed by (23.9).
+     *
      * `refused` is the path of every source whose checked lowering refused, which `diagnoses` has
      * reported at its line — `abide check` emits the rest of the app without them.
      */
     async diagnose(
-        sources: (Omit<ReadSource, 'quiet' | 'position'> & {
-            quiet?: boolean
-            position?: string | undefined
-        })[],
-        within: string,
+        sources: (Omit<ReadSource, 'quiet'> &
+            Partial<Pick<PlacedSource, 'kind' | 'route'>> & {
+                quiet?: boolean
+            })[],
+        app: Pick<AppLayout, 'root' | 'addresses' | 'handlers'>,
         scripts = true,
     ): Promise<{ diagnoses: Diagnosis[]; refused: Set<string> }> {
+        const within = app.root
         const created: string[] = []
         const changed: string[] = []
         const checked: {
@@ -836,13 +822,24 @@ export class TypeSession {
             refusals: readonly Finding[]
         }[] = []
         for (const source of sources) {
-            const shadow = checkedShadow(source.file, source.answer)
+            const shadow = checkedShadow(
+                source.file,
+                source.answer,
+                (source.kind === 'page' || source.kind === 'layout') &&
+                    source.route !== undefined
+                    ? { route: source.route, kind: source.kind }
+                    : undefined,
+            )
             const map = new ShadowMap(
                 this.canonical(source.path),
                 projectShadow(source.file).origins,
                 shadow.origins,
             )
             this.register(map.checkedPath, shadow.text, created, changed)
+            // 23.19 — a package's page an editor opens is reported on, so its checked module is a
+            // root of the project as its shadow is (`classify`).
+            if (!source.quiet)
+                this.openOutside(source.path, map.checkedPath, changed)
             checked.push({ source, map, refusals: shadow.refusals })
         }
         // 34.6 — WHAT THE BUNDLER RESOLVES AND THE CHECKER CANNOT: a stylesheet imported for its
@@ -854,30 +851,23 @@ export class TypeSession {
             created,
             changed,
         )
-        if (this.walked?.within !== within) {
-            // A refused tree is `checkApp`'s finding (38.33), never the checker's crash.
-            const files = appFiles(within, () => {})
-            this.walked = {
-                within,
-                routes: routesDeclaration(within, files),
-                configModules: configModulesUnder(within, files),
-            }
-        }
         // 27.13 — what a handler file defaults, beside it.
-        for (const [path, text] of await this.walked.configModules) {
-            const shadow = moduleConfigShadow(text)
-            const at = `${this.canonical(path)}${CONFIG_SUFFIX}`
+        for (const handler of app.handlers) {
+            const at = `${this.canonical(handler.path)}${CONFIG_SUFFIX}`
+            const shadow = handler.hooks.includes('onConfig')
+                ? moduleConfigShadow(handler.text)
+                : undefined
             // One that stops filing keeps its place and declares nothing, so the next snapshot is
             // told it moved.
             if (shadow !== undefined || this.shadows.has(this.keyOf(at)))
                 this.register(at, shadow ?? 'export {}\n', created, changed)
         }
-        // 30.26 — THE APP'S ROUTE TABLE, which `url`'s literal is held to: every page under the
-        // root, declared into abide's own `Routes`. A module rather than a script, since only a
+        // 30.26 — THE APP'S ROUTE TABLE, which `url`'s literal is held to: every page the build
+        // routes, declared into abide's own `Routes`. A module rather than a script, since only a
         // module augments one.
         this.register(
             `${this.canonical(within)}/${ROUTES_DECLARATION}`,
-            this.walked.routes,
+            routesDeclaration(app.addresses),
             created,
             changed,
         )
@@ -1056,7 +1046,7 @@ export class TypeSession {
             const named = (node as { name?: Node }).name ?? node
             const file = node.getSourceFile()
             definitions.push(
-                this.placeOf(
+                this.spanInSource(
                     file.fileName,
                     file.text,
                     named.getStart(file),
@@ -1078,7 +1068,7 @@ export class TypeSession {
      * back through both of its maps, and one this session has not lowered — or a span of the
      * scaffolding a lowering adds, which the author never wrote — placed at its top.
      */
-    private placeOf(
+    private spanInSource(
         fileName: string,
         text: string,
         start: number,
@@ -1153,23 +1143,10 @@ function isFile(path: string): boolean {
 const ROUTES_DECLARATION = 'abide-routes.d.ts'
 const URL_SOURCE = Bun.fileURLToPath(new URL('../shared/url', import.meta.url))
 
-/**
- * 30.26 — every page under `root`, and every public file's address, as a key of abide's `Routes`, or
- * nothing where it has neither.
- */
-function routesDeclaration(
-    root: string,
-    { abide, published }: ReturnType<typeof appFiles>,
-): string {
-    const routes = new Set<string>()
-    for (const path of abide)
-        if (fileKind(path) === 'page') routes.add(routeOf(path))
-    // 23.19 — and every page a mount places in the app, at its position.
-    for (const { position } of mountedUnder(root, abide))
-        if (fileKind(position) === 'page') routes.add(routeOf(position))
-    for (const address of published.values()) routes.add(address)
+/** 30.26 — each of `addresses` as a key of abide's `Routes`. */
+function routesDeclaration(addresses: readonly string[]): string {
     let keys = ''
-    for (const route of [...routes].sort())
+    for (const route of addresses)
         keys += `        ${JSON.stringify(route)}: true\n`
     return `export {}\ndeclare module ${JSON.stringify(URL_SOURCE)} {\n    interface Routes {\n${keys}    }\n}\n`
 }
@@ -1327,21 +1304,3 @@ function flatten(diagnostic: {
 
 /** What a module that is no `.abide` is checked beside as, for the `Config` it files (27.13). */
 const CONFIG_SUFFIX = '.config-shadow.ts'
-
-/**
- * Every handler file below `within` that names `onConfig`, with its text — the modules a server
- * runs that 27.13 types `Config` off, since 37.13 refuses a hook anywhere else that is no `.abide`.
- */
-async function configModulesUnder(
-    within: string,
-    { handlers }: ReturnType<typeof appFiles>,
-): Promise<[string, string][]> {
-    const paths: string[] = []
-    for (const name of handlers) paths.push(`${within}/${name}`)
-    const texts = await Promise.all(paths.map((path) => Bun.file(path).text()))
-    const found: [string, string][] = []
-    for (let at = 0; at < paths.length; at += 1)
-        if ((texts[at] as string).includes('onConfig'))
-            found.push([paths[at] as string, texts[at] as string])
-    return found
-}