@abide/abide 0.100.0 → 0.102.0

package/src/server/manifestOf.ts

@@ -1,22 +1,26 @@
-// 38.5 AND 38.29 — THE MANIFEST: the files the entry was written under, and each module a route
+// 38.5 AND 38.28 — THE MANIFEST: the files the entry was written under, and each module a route
 // loads in a browser to every chunk that module needs before it can run. Read off the bundler's
 // own metafile rather than off the emitted code, so a chunk the bundler hoisted into a shared file
 // is in the list because the bundler says it is imported, not because a pattern over its output
 // happened to match.
 //
 // THE ENTRY'S NAME IS HERE BECAUSE A BUILD HASHES IT (38.5). `abide dev` names it by its source
-// (38.17) and reads it off this all the same, so the tags the document carries come from one
+// (38.16) and reads it off this all the same, so the tags the document carries come from one
 // place in both lanes rather than from a constant in one and a lookup in the other.
 //
 // THE STATIC CLOSURE AND NOTHING ELSE. An `import-statement` edge is a chunk the module cannot
 // run without; a `dynamic-import` edge is a destination somebody may never navigate to, and
 // preloading it is the whole route table on every page.
 //
-// THE ENTRY IS LEFT OUT of every list, because the document already loads it by name (38.23) and
+// THE ENTRY IS LEFT OUT of every list, because the document already loads it by name (38.22) and
 // a preload of the same address is a second request line for bytes already on their way.
 
 import { resolve } from 'node:path' // bun exposes no path helpers of its own
 import { CLIENT_ENTRY } from './CLIENT_BUILD.ts'
+import { VIRTUAL_DIRECTORY } from './VIRTUAL_DIRECTORY.ts'
+
+// The entry's key: the table it is served as, below the root.
+const ENTRY_MODULE = `${VIRTUAL_DIRECTORY}/${CLIENT_ENTRY}.ts`
 
 export type Manifest = {
     /** The entry's file name, or undefined where the bundle has none — a dev build that failed. */
@@ -24,10 +28,10 @@ export type Manifest = {
     /**
      * The stylesheet the bundler collected under the entry, or undefined where none was imported.
      *
-     * 38.24.
+     * 38.23.
      */
     stylesheet: string | undefined
-    /** A module's path below `base` to the chunk file names it needs, its own first. */
+    /** A module's path below the root — a route's `.abide` — to the chunk file names it needs, its own first. */
     chunks: Record<string, string[]>
 }
 
@@ -40,19 +44,18 @@ export const NO_MANIFEST: Manifest = {
 /**
  * The manifest read off a bundle's metafile: the entry, its stylesheet, and each module's chunks.
  *
- * `base` IS THE TREE THE ROUTE TABLE NAMES MODULES BELOW. The metafile names a file on disk
- * relative to the working directory with symlinks resolved, and a module a plugin served under its
- * namespace as the plugin spelled it — so `abide build` passes its output's real path, and
- * `abide dev` passes the virtual directory its plugin resolves into.
+ * `root` IS THE TREE THE ROUTE TABLE NAMES MODULES BELOW, as its real path: the metafile names a file
+ * relative to the working directory with symlinks resolved, and a table the plugin served under its
+ * namespace as the plugin spelled it (`abideModules`).
  */
 export function manifestOf(
     metafile: Bun.BuildMetafile,
-    base: string,
+    root: string,
 ): Manifest {
     const manifest: Manifest = { ...NO_MANIFEST, chunks: {} }
     const imports = new Map<string, string[]>()
     const modules = new Map<string, string>()
-    const prefix = `${base}/`
+    const prefix = `${root}/`
     for (const [output, described] of Object.entries(metafile.outputs)) {
         if (!isModule(output)) continue
         const statically: string[] = []
@@ -66,7 +69,7 @@ export function manifestOf(
         if (!path.startsWith(prefix)) continue
         const module = path.slice(prefix.length)
         modules.set(module, chunkName(output))
-        if (module !== `${CLIENT_ENTRY}.ts`) continue
+        if (module !== ENTRY_MODULE) continue
         manifest.entry = chunkName(output)
         // NOT IN bun-types, and in the metafile: the stylesheet an entry's CSS was collected into.
         const sheet = (described as { cssBundle?: string }).cssBundle
@@ -103,7 +106,7 @@ export function chunksOf(modules: string[], manifest: Manifest): string[] {
  *
  * A MODULE, NOT A STYLESHEET. The bundler reports the CSS it collected both as a static import of
  * the entry and as an output whose entry point IS the entry — so unfiltered it is fetched as a
- * script, and it takes the entry's own place in the manifest. 38.24 links it already.
+ * script, and it takes the entry's own place in the manifest. 38.23 links it already.
  */
 function isModule(output: string): boolean {
     return output.endsWith('.js')

package/src/server/namesUnder.ts

@@ -1,8 +1,8 @@
 /**
  * The paths below `directory` that `pattern` matches, or none for a directory that is not there.
  *
- * A missing directory is the common case rather than an error: an app has no `ui/public` or
- * `server/rpc` until its author adds one. Narrowed to that one code for `shellUnder`'s reason: a
+ * A missing directory is the common case rather than an error: a build has no `client/` or
+ * `public/` until it writes one. Narrowed to that one code because a
  * directory that exists and cannot be read is a different fault and must not read as an empty one.
  */
 export function namesUnder(directory: string, pattern = '**/*'): string[] {

package/src/server/nativeMenu.ts

@@ -1,4 +1,4 @@
-// THE DESKTOP APP'S MENU BAR (38.89): the default, with what the page the window shows exports,
+// THE DESKTOP APP'S MENU BAR (38.88): the default, with what the page the window shows exports,
 // built as an `NSMenu`.
 
 import { FFIType } from 'bun:ffi'
@@ -27,8 +27,8 @@ export type NativeItem =
           items?: NativeItem[] | undefined
       }
 
-// 38.90 — A ROLE AppKit ALREADY ANSWERS is sent down the responder chain, so `copy` copies whatever
-// holds the selection and is greyed where nothing does. The rest are the launcher's own.
+// 38.89 — A ROLE AppKit ALREADY ANSWERS is sent down the responder chain, so `copy` copies whatever
+// holds the selection and is grayed where nothing does. The rest are the launcher's own.
 const RESPONDER_ROLES: Partial<Record<MenuRole, string>> = {
     about: 'orderFrontStandardAboutPanel:',
     hide: 'hide:',
@@ -76,8 +76,8 @@ const NAMED_KEYS: Record<string, string> = {
 /**
  * The menu bar the window shows: the application, File, Edit, View and Window menus, and `added`.
  *
- * 38.89 — AN ADDED MENU NAMED AS A DEFAULT ONE GROWS IT, and any other stands before Window, where
- * the platform puts an app's own. 38.84 — no Connect… where `launcher.json` turns connecting off.
+ * 38.88 — AN ADDED MENU NAMED AS A DEFAULT ONE GROWS IT, and any other stands before Window, where
+ * the platform puts an app's own. 38.83 — no Connect… where the `launcher` export turns connecting off.
  */
 export function menuBar(
     appName: string,

package/src/server/negotiateEncoding.ts

@@ -1,4 +1,4 @@
-// 38.30 — WHICH OF THE ENCODINGS ON OFFER A REQUEST TAKES, or `undefined` for the bytes as they
+// 38.29 — WHICH OF THE ENCODINGS ON OFFER A REQUEST TAKES, or `undefined` for the bytes as they
 // are. What is on offer is asked rather than assumed: a request preferring brotli for a file with
 // only a gzip copy takes the gzip, where picking first and checking after would send it neither.
 //

package/src/server/principal.ts

@@ -20,7 +20,7 @@ import { declare } from '#shared/rpc.ts'
 import { mountedOwn } from './answerRpc.ts'
 import { callerOrMint, mintCaller } from './callerOf.ts'
 import { config, positiveSetting } from './config.ts'
-import { HOOKS } from './hooks.ts'
+import { HOOKS, inOrder } from './hooks.ts'
 import { within } from './requestScope.ts'
 
 // 26.18.
@@ -150,12 +150,17 @@ async function documentOf(
         expiresAt: new Date(expires).toISOString(),
         error: undefined,
     }
-    const resolve = HOOKS.principal
-    if (resolve === undefined)
+    const resolvers = inOrder(HOOKS.principal)
+    if (resolvers.length === 0)
         return { ...(isRecord(claims) ? claims : {}), ...baseline }
     try {
-        const resolved = await resolve(claims)
-        return { ...(isRecord(resolved) ? resolved : {}), ...baseline }
+        // 37.7 — EVERY RESOLVER, handed the claims, its answer merged over the ones before it.
+        const resolved: Record<string, unknown> = {}
+        for (const resolve of resolvers) {
+            const answered = await resolve(claims)
+            if (isRecord(answered)) Object.assign(resolved, answered)
+        }
+        return { ...resolved, ...baseline }
     } catch (thrown) {
         // 26.3 — a resolver that failed leaves the caller unauthenticated, and says why.
         PRINCIPAL_LOG.warning('onPrincipal threw', thrown)

package/src/server/realOrAsGiven.ts

@@ -0,0 +1,10 @@
+import { realpathSync } from 'node:fs' // bun exposes no realpath of its own
+
+// A root that is not there is refused by the command that reads it, at the path it was given.
+export function realOrAsGiven(path: string): string {
+    try {
+        return realpathSync(path)
+    } catch {
+        return path
+    }
+}

package/src/server/refuseAddressCollision.ts

@@ -1,30 +1,37 @@
-import { PUBLIC_DIRECTORY } from './CLIENT_BUILD.ts'
-
 /**
- * Throws, naming both, when a public file and a page claim the same address.
+ * Throws, naming both, when a public file claims a route's address or another public file's.
  *
- * 36.13 — A PUBLIC FILE AND A PAGE MAY NOT CLAIM ONE ADDRESS. The two are separate walks of two
- * separate trees, so from inside either one the collision is invisible; this is the one place
- * they meet, and naming BOTH is the clause — naming one leaves the reader to find the other.
+ * 36.13 — the walks that find routes and public files cannot see each other's collisions from
+ * inside either one; this is the one place they meet, and naming BOTH is the clause — naming one
+ * leaves the reader to find the other. Two `public` directories can claim one address too, since
+ * each mounts at the path above it (36.11).
  *
  * THE BUILD AND DEV, and `abide start` trusts the build: `answerRequest` answers a public file
  * AHEAD of any route on the ground that 36.13 makes a collision impossible at run time, and 30.8
  * says dev must resolve an address the way the built app does.
  *
- * PUBLIC ADDRESSES IN, so a caller hands whichever it already holds: the build derives one per
- * globbed name (36.11 — the path below the directory IS the address) and the dev worker's
- * `published` map is keyed by them already.
+ * `published` is each public file's source path to its address, as `appTree` reads them.
  */
 export function refuseAddressCollision(
-    routes: readonly { pattern: string }[],
-    publicAddresses: Iterable<string>,
+    pages: readonly { pattern: string }[],
+    handlers: readonly { address: string }[],
+    published: Map<string, string>,
     command: string,
 ): void {
     const patterns = new Set<string>()
-    for (const route of routes) patterns.add(route.pattern)
-    for (const address of publicAddresses)
+    for (const page of pages) patterns.add(page.pattern)
+    for (const handler of handlers) patterns.add(handler.address)
+    const claimed = new Map<string, string>()
+    for (const [source, address] of published) {
         if (patterns.has(address))
             throw new Error(
-                `${command}: ui/${PUBLIC_DIRECTORY}${address} and the page at ${address} claim the same address. RULEBOOK 36.13.`,
+                `${command}: ${source} and the route ${address} claim the same address. RULEBOOK 36.13.`,
             )
+        const other = claimed.get(address)
+        if (other !== undefined)
+            throw new Error(
+                `${command}: ${other} and ${source} are both answered at ${address}. RULEBOOK 36.13.`,
+            )
+        claimed.set(address, source)
+    }
 }

package/src/server/remote.ts

@@ -1,12 +1,13 @@
-// THE CLIENT FOR A RUNNING APP — what the shell (`shell.ts`), `call`, `logs`, `openapi` and `mcp` talk to
+// THE CLIENT FOR A RUNNING APP — what the shell (`shell.ts`), `call`, `watch`, `openapi` and `mcp` talk to
 // it with, the shell on the app served here included.
 // Which app is `--url`, then `ABIDE_APP_URL`, then the local one; `ABIDE_APP_TOKEN` is the bearer
 // sent (36.6), and neither variable is read anywhere else.
 
-import { LOGS_ADDRESS, RPC_ADDRESS } from '#shared/ADDRESSES.ts'
 import { applyPatch } from '#shared/applyPatch.ts'
-import type { LogRecord } from '#shared/log.ts'
+import { filledPath, parametersOf } from '#shared/filledPath.ts'
+import { firstMatch, partsOf } from '#shared/matchRoute.ts'
 import type { PatchOp } from '#shared/reactive/PATCH_SINKS.ts'
+import { rankRoutes } from '#shared/routePattern.ts'
 import type { Method } from '#shared/rpc.ts'
 import { argsInURL, rpcRequest } from '#shared/rpcRequest.ts'
 import type { Mount } from './answerRpc.ts'
@@ -43,8 +44,8 @@ const FAULTED = 8
 /**
  * Calls one handler on a running app; returns the CLI's exit code and the answer's text.
  *
- * 38.8 — ONE CALL TO ONE HANDLER, spelled `invoices/getInvoice id=4310` in argv and in the shell
- * alike, and 38.62's args.
+ * 38.8 — ONE CALL TO ONE HANDLER, spelled `invoices/getInvoice id=4310` — or `invoices/4310` where
+ * the route carries the parameter — in argv and in the shell alike, and 38.61's args.
  */
 export async function callHandler(
     url: string,
@@ -54,10 +55,11 @@ export async function callHandler(
     handlers: Mount[],
     signal?: AbortSignal,
 ): Promise<{ code: number; text: string }> {
-    const address = `${RPC_ADDRESS}/${path.replace(/^\//, '')}`
-    const handler = handlers.find((mount) => mount.address === address)
+    const address = `/${path.replace(/^\//, '')}`
+    const asked = method?.toUpperCase()
+    const handler = handlerAt(handlers, address, asked)
     const args = callArgs(given)
-    const chosen = (method?.toUpperCase() ??
+    const chosen = (asked ??
         (handler?.method as Method | undefined) ??
         (args === undefined ? 'GET' : 'POST')) as Method
     const request =
@@ -78,7 +80,7 @@ export async function callHandler(
 /**
  * A call's args out of the words after its address, or `undefined` where there are none.
  *
- * 38.62 — `name=value` words, kept as the text they are for the app to coerce as it coerces a query's
+ * 38.61 — `name=value` words, kept as the text they are for the app to coerce as it coerces a query's
  * (19.7), against the schema it holds the call to; or, where the first word opens one, a JSON object.
  */
 function callArgs(
@@ -102,12 +104,45 @@ function callArgs(
     return pairs
 }
 
-/** The request a call with text args is: in the URL where its method carries them, a form where not. */
+/**
+ * The handler `address` names: its route as written (`media/[id]`), or an address its route matches
+ * (`media/4310`) — the most specific, of `method` where one is asked for.
+ */
+function handlerAt(
+    handlers: Mount[],
+    address: string,
+    method: string | undefined,
+): Mount | undefined {
+    const rows: { pattern: string; mount: Mount }[] = []
+    for (const mount of handlers) {
+        if (method !== undefined && mount.method !== method) continue
+        if (mount.address === address) return mount
+        rows.push({ pattern: mount.address, mount })
+    }
+    return firstMatch(rankRoutes(rows), partsOf(address) ?? [])?.route.mount
+}
+
+/**
+ * The request a call with text args is: in the URL where its method carries them, a form where not.
+ *
+ * 16.9 — a route written with its parameters takes them out of the args and into the path.
+ */
 function textRequest(
     method: Method,
-    address: string,
-    pairs: URLSearchParams,
+    route: string,
+    given: URLSearchParams,
 ): { url: string; init: RequestInit } {
+    let address = route
+    let pairs = given
+    if (route.includes('[')) {
+        const params: Record<string, string> = {}
+        pairs = new URLSearchParams()
+        const named = parametersOf(route)
+        for (const [name, value] of given)
+            if (named.has(name)) params[name] = value
+            else pairs.append(name, value)
+        address = filledPath(route, params, route)
+    }
     if (argsInURL(method))
         return { url: `${address}?${pairs}`, init: { method } }
     return {
@@ -120,49 +155,11 @@ function textRequest(
     }
 }
 
-/**
- * Prints every line `log.records` publishes, as it is written; returns the exit code.
- *
- * 38.10.
- */
-export async function followLogs(url: string): Promise<number> {
-    const answer = await fetch(`${url}${LOGS_ADDRESS}`, {
-        headers: { ...remoteHeaders(), accept: 'text/event-stream' },
-    })
-    if (!answer.ok || answer.body === null) {
-        console.error(
-            `logs: the app answered ${answer.status}. ABIDE_LOGS opens the subscription.`,
-        )
-        return 1
-    }
-    // 18.20 — the lines held arrive as the value, and each line after as an `add` at `/-`; a trim's
-    // `remove`s are the buffer letting old lines go, which a tail has already printed.
-    for await (const event of eventsOf(answer.body)) {
-        if (event.name === 'error') console.error(`logs: ${event.data}`)
-        const lines =
-            event.name === 'value'
-                ? ((JSON.parse(event.data) as LogRecord[] | null) ?? [])
-                : event.name === 'patch'
-                  ? addedBy(JSON.parse(event.data) as PatchOp[])
-                  : []
-        for (const { time, level, namespace, message } of lines)
-            console.log(`${time} ${level} ${namespace} ${message}`)
-    }
-    return 0
-}
-
-/** The records a patch appended: the value of each `add`. */
-function addedBy(ops: PatchOp[]): LogRecord[] {
-    const added: LogRecord[] = []
-    for (const op of ops) if (op.op === 'add') added.push(op.value as LogRecord)
-    return added
-}
-
 /**
  * Follows a `GET` of the app at `url` as an event stream, printing its value and its value after each
  * patch; returns the exit code.
  *
- * 38.70, 18.20 — THE EVENT STREAM ANY CLIENT MAY ASK A FOLLOWED `GET` FOR, read by one: `event: value`
+ * 38.69, 18.20 — THE EVENT STREAM ANY CLIENT MAY ASK A FOLLOWED `GET` FOR, read by one: `event: value`
  * replaces what is held and `event: patch` is JSON Patch applied over it. A handler the server does
  * not follow — one built per request — answers once, and is printed once.
  */
@@ -172,7 +169,7 @@ export async function watch(
     given: string[],
     signal?: AbortSignal,
 ): Promise<number> {
-    const path = `${RPC_ADDRESS}/${address.replace(/^\//, '')}`
+    const path = `/${address.replace(/^\//, '')}`
     const args = callArgs(given)
     const request =
         args instanceof URLSearchParams

package/src/server/render.ts

@@ -27,17 +27,25 @@ import { currentRequestScope, type PageCall } from './requestScope.ts'
 // biome-ignore lint/suspicious/noEmptyInterface: REGISTRY declares `interface Component {}`.
 export interface Component {}
 
-/** The document a render renders into, defaulting to `src/ui/app.html`. 35.6. */
-export type Shell = string | URL | undefined
-
-// Where a shell was not given and `src/ui/app.html` is not there either. The rulebook does not
-// say what happens in that case; serving nothing would be worse than serving this.
-const BARE_SHELL = '<!doctype html><html><head></head><body></body></html>'
+/**
+ * 35.6 — THE DOCUMENT EVERY RENDER WRITES INTO: an encoding and a viewport, each keyed, so the
+ * component's own replace them (35.15), and nothing else — what a document carries beyond that is
+ * the component's to write.
+ */
+export const DEFAULT_DOCUMENT =
+    '<!doctype html><html><head><meta charset="utf-8"><meta name="viewport" content="width=device-width, initial-scale=1"></head><body></body></html>'
 
 const ENCODER = new TextEncoder()
 
-/** What a compiled component answers: its head and its body markup. */
-export type Rendered = { head: string; body: string }
+/**
+ * What a compiled component answers: its head and its body markup, and the document's `<html>`
+ * and `<body>` it writes, rendered empty (35.15), or `undefined`.
+ */
+export type Rendered = {
+    head: string
+    body: string
+    document: { html: string; body: string } | undefined
+}
 
 /**
  * The page inside its layouts, every level set up first and then built.
@@ -85,7 +93,12 @@ export async function composePage(
     // THE OUTERMOST HEAD FIRST: reading it builds the chain, which is what pushes the heads below.
     // Written end to end rather than merged: `render` merges it with the shell's in one pass (39.4).
     const head = outermost.head
-    return { head: head + heads.join(''), body: outermost.body }
+    return {
+        head: head + heads.join(''),
+        body: outermost.body,
+        // 35.15 — the document's, which only the root layout writes, and it is outermost.
+        document: outermost.document,
+    }
 }
 
 /**
@@ -185,46 +198,6 @@ function dropShadowed(markup: string, total: Map<string, number>): string {
     })
 }
 
-/**
- * The keyed elements at the top of a shell's head, end to end, and nothing else.
- *
- * 39.14 — WHAT A CLIENT NAVIGATION PUTS BACK. `mergeHead` drops every shell entry a level
- * overrides, so once the server has painted the document the shell's `<title>` is nowhere a
- * browser can read it — and a navigation to a page with no title owes it back. The build hands
- * these to the router rather than the server writing them into each page: the shell is one per
- * app, so it rides in the route table once instead of in every document. KEYED ONLY, because an
- * entry with no key is never withdrawn (39.5) and a shell's inline `<style>` would be the route
- * table's largest string for nothing. Top level only, as `mergeHead` keys it.
- */
-export function keyedHead(document: string): string {
-    const unwrap = {
-        element(element: HTMLRewriterTypes.Element) {
-            element.removeAndKeepContent()
-        },
-    }
-    const top = { depth: 0 }
-    const rewriter = new HTMLRewriter()
-        .onDocument({
-            doctype(doctype) {
-                doctype.remove()
-            },
-            comments(comment) {
-                comment.remove()
-            },
-            text(text) {
-                if (top.depth === 0) text.remove()
-            },
-        })
-        .on('html', unwrap)
-        .on('head', unwrap)
-    return dropAtHeadTop(
-        rewriter,
-        document.slice(0, headAnchor(document)),
-        (key) => key === undefined,
-        top,
-    )
-}
-
 /**
  * `markup` through `rewriter`, with each element at the top of the head removed where `drop`
  * answers true for its key — `undefined` for an element with none. `top` is the depth the walk is
@@ -300,23 +273,25 @@ export function boundPage(
 }
 
 /**
- * The document's bytes: `component` rendered into `shell`.
+ * The document's bytes: `component` rendered into abide's own document (35.6).
  *
  * 35.4, 35.5 — the component is already bound to its props.
  */
-export async function render(
+export function render(component: Component): Promise<Uint8Array<ArrayBuffer>> {
+    return renderDocument(component, DEFAULT_DOCUMENT)
+}
+
+/**
+ * `render` into `given`: abide's own document with what the server adds to it — a page's client
+ * tags, the launcher page's stylesheet. NOT PUBLIC SURFACE — `server/index.ts` exports `render`.
+ */
+export async function renderDocument(
     component: Component,
-    shell?: Shell,
+    given: string,
 ): Promise<Uint8Array<ArrayBuffer>> {
-    // GUARDED, because the string form is already settled: `shellText` is `async`, so awaiting it
-    // unconditionally wrapped a promise and spent a microtask turn per request for nothing.
-    const document = typeof shell === 'string' ? shell : await shellText(shell)
-
     // TWO INSERTION POINTS, CLAMPED AND ORDERED. `</head>` and `</body>` are both OPTIONAL end
     // tags, so a valid shell can carry neither: an absent anchor means "the end of the document",
     // and the clamp is what keeps the head ahead of the body whatever order the shell wrote them in.
-    const bodyAt = bodyAnchor(document)
-    const headAt = headAnchor(document)
     // 41.1 — NOTHING GOES OUT UNTIL THE PAGE IS BUILT. The status line goes out with the first byte,
     // and a page reading a record that is not there is a 404 only while no byte has: so the page and
     // its layouts are set up (41.19) and built before the shell's head is sent, and a refusal or a
@@ -331,6 +306,13 @@ export async function render(
     const rendered = isThenable(answered) ? await answered : answered
     const head = rendered.head
     const body = rendered.body
+    // 35.15 — the root layout's `<html>` and `<body>` attributes, on the document's own two.
+    const document =
+        rendered.document === undefined
+            ? given
+            : withDocumentAttributes(given, rendered.document)
+    const bodyAt = bodyAnchor(document)
+    const headAt = headAnchor(document)
     // 41.20 — THE PAGE'S CALLS LEAVE AHEAD OF ITS MARKUP. Setup has run, so every call the page
     // makes is known, and a script in the head starts each one as the request the browser's own
     // `Rpc` would make — while the rest of the document and the bundle are still on their way.
@@ -399,13 +381,20 @@ function bodyAnchor(document: string): number {
 }
 
 /**
- * Where a shell's head ends, clamped ahead of its body.
+ * The shell with `tags` at the head anchor `render` uses.
  *
- * NOT PUBLIC SURFACE: `server/index.ts` does not re-export it. `answerRequest` is the second
- * caller — a shell has to carry the client entry's script tag (38.23), and putting that anywhere
- * but the head this finds is the same clamped-and-ordered question over again.
+ * So a shell with no `</head>` puts them where its head content goes rather than inside the body.
+ * NOT PUBLIC SURFACE: `server/index.ts` does not re-export it. A shell has to carry the client
+ * entry's script tag (38.22), and putting that anywhere but the head `render` finds is the same
+ * clamped-and-ordered question over again.
  */
-export function headAnchor(document: string): number {
+export function intoHead(shell: string, tags: string): string {
+    const at = headAnchor(shell)
+    return shell.slice(0, at) + tags + shell.slice(at)
+}
+
+/** Where a shell's head ends, clamped ahead of its body. */
+function headAnchor(document: string): number {
     const bodyAt = bodyAnchor(document)
     // THE OPENING `<body` IS THE FALLBACK, not the body anchor. Collapsed onto `bodyAt`, a shell
     // with no `</head>` put the page's `<title>`, `<meta>` and stylesheet links after the mount
@@ -428,37 +417,19 @@ function bodyOpen(document: string): number {
 }
 
 /**
- * The text of a shell given as a URL, or of the default one.
+ * `document` with the attributes `written` carries — an `<html …></html>` and a `<body …></body>`,
+ * each rendered empty — written onto its own `<html>` and `<body>` tags.
  *
- * The URL and absent forms only — the string form is already settled and its caller above takes
- * it without a turn, so a second copy of that test here is a branch nothing reaches and a second
- * owner of the question.
+ * 35.15, 35.17 — RENDERED AS ANY ELEMENT IS, so an attribute is escaped, absent or live exactly as
+ * one on a `<div>` is, and lifted off the rendered pair by its fixed frame rather than parsed.
  */
-async function shellText(shell: URL | undefined): Promise<string> {
-    if (shell !== undefined) return await Bun.file(shell).text()
-    return await shellUnder('src')
-}
-
-/**
- * The shell at `<root>/ui/app.html`, or a bare document where there is none.
- *
- * 35.6's default, read from a ROOT rather than from the process's directory. `render` on its own
- * is called from wherever the app is, so `src` is the root it passes; `loadBuild` is handed the
- * root `abide build` compiled and the two need not be the same directory. NOT PUBLIC SURFACE —
- * `server/index.ts` does not re-export it.
- */
-export async function shellUnder(root: string): Promise<string> {
-    // `.text()` already fails when the file is not there, so no `.exists()` asks first. The read
-    // happens per render for a bare `render` call — 20 µs and 98% of the op — and `loadBuild` is the caller that hoists
-    // it, reading the shell once at boot rather than once a request.
-    try {
-        return await Bun.file(`${root}/ui/app.html`).text()
-    } catch (thrown) {
-        // NARROWED TO THE ONE CASE THE LINE ABOVE ARGUES FOR. A bare catch made every failure look
-        // like an absent file, so a project that HAS a shell which is momentarily unreadable —
-        // EACCES, EISDIR, EMFILE under load — was served the bare shell with no stylesheet, no
-        // client script and nothing said, on one request in a thousand.
-        if ((thrown as { code?: unknown }).code !== 'ENOENT') throw thrown
-        return BARE_SHELL
-    }
+function withDocumentAttributes(
+    document: string,
+    written: { html: string; body: string },
+): string {
+    const html = written.html.slice('<html'.length, -'></html>'.length)
+    const body = written.body.slice('<body'.length, -'></body>'.length)
+    return document
+        .replace(/<html(?=[\s>])/i, `<html${html}`)
+        .replace(/<body(?=[\s>])/i, `<body${body}`)
 }

package/src/server/renderComponent.ts

@@ -28,6 +28,11 @@ export function renderComponent(
     const rendered = (
         component as (props: Record<string, () => unknown>) => Rendered
     )(props)
+    // 35.16 — a document is written by the outermost component alone, and this one is placed.
+    if (rendered.document !== undefined)
+        throw new Error(
+            'abide: a component that writes <html> is placed inside another, and only the outermost component writes the document. RULEBOOK 35.16.',
+        )
     if (rendered.head !== '') heads.push(rendered.head)
     return regionMarkup(rendered.body)
 }

package/src/server/reportHealth.ts

@@ -9,7 +9,7 @@ import { isRecord } from '#shared/isRecord.ts'
 import { namedLogger } from '#shared/log.ts'
 import abidePackage from '../../package.json' with { type: 'json' }
 import { appIdentity, config } from './config.ts'
-import { HOOKS } from './hooks.ts'
+import { HOOKS, inOrder } from './hooks.ts'
 
 const HEALTH_LOG = namedLogger('abide:health')
 
@@ -23,7 +23,7 @@ export async function reportHealth(): Promise<Health> {
         abide: abidePackage.version,
         startedAt: STARTED_AT,
     }
-    for (const report of HOOKS.health) {
+    for (const report of inOrder(HOOKS.health)) {
         let answered: unknown
         try {
             answered = await report()